distribution/docs/nginx.md
Olivier Gambier 34067d7d43 Documentation work
- move away insecure & self-signed
- introduce native basic auth
- move "down" nginx based authentication
- overall shortening / smoothing of "deploying" documentation

Signed-off-by: Olivier Gambier <olivier@docker.com>
2015-08-10 13:57:35 -07:00

147 lines
4.6 KiB
Markdown

<!--[metadata]>
+++
title = "Authentication for the Registry with a proxy"
description = "Restricting access to your registry using a proxy"
keywords = ["registry, service, images, repository, authentication"]
[menu.main]
parent="smn_registry"
+++
<![end-metadata]-->
# Authenticating proxy with nginx
With this method, you implement basic authentication in a reverse proxy that sits in front of your registry.
While this model gives you the ability to use whatever authentication backend you want through a secondary authentication mechanism implemented inside your proxy, it also requires that you move TLS termination from the Registry to the proxy itself.
Furthermore, introducing an extra http layer in your communication pipeline will make it more complex to deploy, maintain, and debug, and will possibly create issues (typically, nginx does buffer client requests to disk, opening the door to a host of problems if you are dealing with huge images and a lot of traffic).
### Requirements
You should have followed entirely the basic [deployment guide](deploying.md).
If you have not, please take the time to do so.
At this point, it's assumed that:
* you understand Docker security requirements, and how to configure your docker engines properly
* you have installed Docker Compose
* it's HIGHLY recommended that you get a certificate from a known CA instead of self-signed certificates
* inside the current directory, you have a X509 `domain.crt` and `domain.key`, for the CN `myregistrydomain.com` (or whatever domain name you want to use)
* be sure you have stopped and removed any previously running registry (typically `docker stop registry && docker rm -v registry`)
### Setting things up
Read again the requirements.
Ready?
Run the following:
```
mkdir -p auth
mkdir -p data
# This is the main nginx configuration you will use
cat <<EOF > auth/registry.conf
upstream docker-registry {
server registry:5000;
}
server {
listen 443 ssl;
server_name myregistrydomain.com;
# SSL
ssl_certificate /etc/nginx/conf.d/domain.crt;
ssl_certificate_key /etc/nginx/conf.d/domain.key;
# disable any limits to avoid HTTP 413 for large image uploads
client_max_body_size 0;
# 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;
}
# To add basic authentication to v2 use auth_basic setting plus add_header
auth_basic "Registry realm";
auth_basic_user_file /etc/nginx/conf.d/htpasswd;
add_header 'Docker-Distribution-Api-Version' 'registry/2.0' always;
proxy_pass http://docker-registry;
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 X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
proxy_read_timeout 900;
}
}
EOF
# Now, create a password file for "testuser" and "testpassword"
htpasswd -bn testuser testpassword > auth/htpasswd
# Copy over your certificate files
cp domain.crt auth
cp domain.key auth
# Now create your compose file
cat <<EOF > docker-compose.yml
nginx:
image: "nginx:1.9"
ports:
- 5043:443
links:
- registry:registry
volumes:
- `pwd`/auth/:/etc/nginx/conf.d
registry:
image: registry:2
ports:
- 127.0.0.1:5000:5000
environment:
REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
volumes:
- `pwd`/data:/data
EOF
```
### Starting and stopping
That's it. You can now:
* `docker-compose up -d` to start your registry
* `docker login myregistrydomain.com:5043` (using `testuser` and `testpassword`)
* `docker tag ubuntu myregistrydomain.com:5043/toto`
* `docker push myregistrydomain.com:5043/toto`
### Docker still complains about the certificate?
That's certainly because you are using a self-signed certificate, despite the warnings.
If you really insist on using these, you have to trust it at the OS level.
Usually, on Ubuntu this is done with:
```
cp auth/domain.crt /usr/local/share/ca-certificates/myregistrydomain.com.crt
update-ca-certificates
```
... and on RedHat with:
```
cp auth/domain.crt /etc/pki/ca-trust/source/anchors/myregistrydomain.com.crt
update-ca-trust
```
Now:
* `service docker stop && service docker start` (or any other way you use to restart docker)
* `docker-compose up -d` to bring your registry up