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 6c408534..3b586b4c 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;
+}
+```