From 6f087829c9e999d07b01fb5af80a53f5cfb083a0 Mon Sep 17 00:00:00 2001
From: Derek McGowan <derek@mcgstyle.net>
Date: Fri, 10 Apr 2015 15:16:13 -0700
Subject: [PATCH] Add nginx configuration for v1 and v2 registry

Signed-off-by: Derek McGowan <derek@mcgstyle.net> (github: dmcgowan)
---
 docs/deploying.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/docs/deploying.md b/docs/deploying.md
index 6c408534c..3b586b4cc 100644
--- a/docs/deploying.md
+++ b/docs/deploying.md
@@ -406,3 +406,61 @@ middleware:
 **TODO(stevvooe): Need a "best practice" configuration overview. Perhaps, we can point to a documentation section.
 
 
+# Configure nginx to deploy alongside v1 registry
+
+This sections describes how to configure nginx to proxy to both a v1 and v2
+registry. Nginx will handle routing of to the correct registry based on the
+URL and Docker client version.
+
+## Example configuration
+With v1 registry running at `localhost:5001` and v2 registry running at
+`localhost:5002`.  Add this to `/etc/nginx/conf.d/registry.conf`.
+```
+server {
+  listen 5000;
+  server_name localhost;
+
+  ssl on;
+  ssl_certificate /etc/docker/registry/certs/domain.crt;
+  ssl_certificate_key /etc/docker/registry/certs/domain.key;
+
+  client_max_body_size 0; # disable any limits to avoid HTTP 413 for large image uploads
+
+  # required to avoid HTTP 411: see Issue #1486 (https://github.com/docker/docker/issues/1486)
+  chunked_transfer_encoding on;
+
+  location /v2/ {
+    # Do not allow connections from docker 1.5 and earlier
+    # docker pre-1.6.0 did not properly set the user agent on ping, catch "Go *" user agents
+    if ($http_user_agent ~ "^(docker\/1\.(3|4|5(?!\.[0-9]-dev))|Go ).*$" ) {
+      return 404;
+    }
+
+    proxy_pass                       http://localhost:5002;
+    proxy_set_header  Host           $http_host;   # required for docker client's sake
+    proxy_set_header  X-Real-IP      $remote_addr; # pass on real client's IP
+    proxy_read_timeout               900;
+  }
+
+  location / {
+    proxy_pass                       http://localhost:5001;
+    proxy_set_header  Host           $http_host;   # required for docker client's sake
+    proxy_set_header  X-Real-IP      $remote_addr; # pass on real client's IP
+    proxy_set_header  Authorization  ""; # see https://github.com/docker/docker-registry/issues/170
+    proxy_read_timeout               900;
+  }
+}
+```
+
+## Running nginx without a v1 registry
+When running a v2 registry behind nginx without a v1 registry, the `/v1/` endpoint should
+be explicitly configured to return a 404 if only the `/v2/` route is proxied. This
+is needed due to the v1 registry fallback logic within Docker 1.5 and 1.6 which will attempt
+to retrieve content from the v1 endpoint if no content was retrieved from v2.
+
+Add this location block to explicitly block v1 requests.
+```
+localhost /v1/ {
+	return 404;
+}
+```