Signed-off-by: Mary Anthony <mary@docker.com>
19 KiB
Deploying a registry server
This section explains how to deploy a Docker Registry either privately for your own company or publicly for other users. For example, your company may require a private registry to support your continuous integration (CI) system as it builds new releases or test servers. Alternatively, your company may have a large number of products or services with images you wish to serve in a branded manner.
Docker's public registry maintains a default registry
image to assist you in the
deployment process. This registry image is sufficient for running local tests
but is insufficient for production. For production you should configure and
build your own custom registry image from the docker/distribution
code.
Note
If you are running Docker in a different OS, you may need to "translate" the commands to meet the requirements of your own environment.
Simple example with the official image
In this section, you create a container running Docker's official registry image. You push an image to, and then pull the same image from, this registry. This a good exercise for understanding the basic interactions a client has with a local registry.
-
Install Docker.
-
Run the
hello-world
image from the Docker public registry.$ docker run hello-world
The
run
command automatically pulls ahello-world
image from Docker's official images. -
Start a registry on your localhost.
$ docker run -p 5000:5000 registry:2.0
This starts a registry on your
DOCKER_HOST
running on port5000
. -
List your images.
$ docker images REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE registry 2.0 bbf0b6ffe923 3 days ago 545.1 MB golang 1.4 121a93c90463 5 days ago 514.9 MB hello-world latest e45a5af57b00 3 months ago 910 B
Your list should include a
hello-world
image from the earlier run. -
Retag the
hello-world
image for your local repoistory.$ docker tag hello-world:latest localhost:5000/hello-mine:latest
The command labels a
hello-world:latest
using a new tag in the[REGISTRYHOST/]NAME[:TAG]
format. TheREGISTRYHOST
is this case islocalhost
. In a Mac OSX environment, you'd substitute$(boot2docker ip):5000
for thelocalhost
. -
List your new image.
$ docker images REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE registry 2.0 bbf0b6ffe923 3 days ago 545.1 MB golang 1.4 121a93c90463 5 days ago 514.9 MB hello-world latest e45a5af57b00 3 months ago 910 B localhost:5000/hello-mine latest ef5a5gf57b01 3 months ago 910 B
You should see your new image in your listing.
-
Push this new image to your local registry.
$ docker push localhost:5000/hello-mine:latest The push refers to a repository [localhost:5000/hello-mine] (len: 1) e45a5af57b00: Image already exists 31cbccb51277: Image successfully pushed 511136ea3c5a: Image already exists Digest: sha256:a1b13bc01783882434593119198938b9b9ef2bd32a0a246f16ac99b01383ef7a
-
Use the
curl
command and the Docker Registry API v2 to list your image in the registry:$ curl -v -X GET http://localhost:5000/v2/hello-mine/tags/list * Hostname was NOT found in DNS cache * Trying 127.0.0.1... * Connected to localhost (127.0.0.1) port 5000 (#0) > GET /v2/hello-mine/tags/list HTTP/1.1 > User-Agent: curl/7.35.0 > Host: localhost:5000 > Accept: */* > < HTTP/1.1 200 OK < Content-Type: application/json; charset=utf-8 < Docker-Distribution-Api-Version: registry/2.0 < Date: Sun, 12 Apr 2015 01:29:47 GMT < Content-Length: 40 < {"name":"hello-mine","tags":["latest"]} * Connection #0 to host localhost left intact
You can also get this information by entering the
http://localhost:5000/v2/hello-mine/tags/list
address in your browser. -
Remove all the unused images from your local environment:
$ docker rmi -f $(docker images -q -a )
This command is for illustrative purposes; removing the image forces any
run
to pull from a registry rather than a local cache. If you rundocker images
after this you should not see any instance ofhello-world
orhello-mine
in your images list.$ docker images REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE registry 2.0 bbf0b6ffe923 3 days ago 545.1 MB golang 1.4 121a93c90463 5 days ago 514.9 MB
-
Try running
hello-mine
.$ docker run hello-mine Unable to find image 'hello-mine:latest' locally Pulling repository hello-mine FATA[0001] Error: image library/hello-mine:latest not found
The
run
command fails because your new image doesn't exist in the Docker public registry. -
Now, try running the image but specifying the image's registry:
$ docker run localhost:5000/hello-mine
If you run
docker images
after this you'll fine ahello-mine
instance.
Making Docker's official registry image production ready
Docker's official image is for simple tests or debugging. Its configuration is unsuitable for most production instances. For example, any client with access to the server's IP can push and pull images to it. See the next section for information on making this image production ready.
Understand production deployment
The Docker Registry 2.0 only accepts connections from a Docker client that is version 1.6.0 or newer. This means, for example, if you are deploying in a environment with 1.5.X clients you'll need to either upgrade them or deploy an older version of the Docker Registry to support them. For information on how to do this, see Configure Nginx with a v1 and v2 registry on this page.
When deploying a registry for a production deployment you should consider these key factors:
backend storage | Where should you store the images? |
---|---|
access and/or authentication | Should users have full or controlled access? This can depend on whether you are serving images to the public or internally to your company only. |
debugging | When problems or issues arise, do you have the means of solving them. Logs are useful as is reporting to see trends. |
caching | Quickly retrieving images can be crucial if you are relying on images for tests, builds, or other automated systems. |
You can configure your registry features to adjust for these factors. You do this by specifying options on the command line or, more typically, by writing a registry configuration file. The configuration file is in YAML format.
Docker's official repository image is preconfigured using the following configuration file:
version: 0.1
log:
level: debug
fields:
service: registry
environment: development
storage:
cache:
blobdescriptor: inmemory
filesystem:
rootdirectory: /tmp/registry-dev
maintenance:
uploadpurging:
enabled: false
http:
addr: :5000
secret: asecretforlocaldevelopment
debug:
addr: localhost:5001
redis:
addr: localhost:6379
pool:
maxidle: 16
maxactive: 64
idletimeout: 300s
dialtimeout: 10ms
readtimeout: 10ms
writetimeout: 10ms
notifications:
endpoints:
- name: local-8082
url: http://localhost:5003/callback
headers:
Authorization: [Bearer <an example token>]
timeout: 1s
threshold: 10
backoff: 1s
disabled: true
- name: local-8083
url: http://localhost:8083/callback
timeout: 1s
threshold: 10
backoff: 1s
disabled: true
This configuration is very basic and you can see it would present some problems
in a production environment. For example, the http
section details the configuration for
the HTTP server that hosts the registry. The server is not using even the most
minimal transport layer security (TLS). Let's configure that in the next section.
Configure TLS on a registry server
In this section, you configure TLS on the server to enable communication through
the https
protocol. Enabling TLS on the server is the minimum layer of
security recommended for running a registry behind a corporate firewall. One way
to do this is to build your own registry image.
Download the source and generate certificates
-
Alternatively, use the
git clone
command if you are more comfortable with that. -
Unpack the the downloaded package into a local directory.
The package creates a
distribution
directory. -
Change to the root of the new
distribution
directory.$ cd distribution
-
Make a
certs
subdirectory.$ mkdir certs
-
Use SSL to generate some self-signed certificates.
$ openssl req \ -newkey rsa:2048 -nodes -keyout certs/domain.key \ -x509 -days 365 -out certs/domain.crt
This command prompts you for basic information it needs to create the certificates.
-
List the contents of the
certs
directory.$ ls certs domain.crt domain.key
When you build this container, the
certs
directory and its contents automatically get copied also.
Add TLS to the configuration
The distribution
repo includes sample registry configurations in the cmd
subdirectory. In this section, you edit one of these configurations to add TLS
support.
-
Edit the
./cmd/registry/config.yml
file.$ vi ./cmd/registry/config.yml
-
Locate the
http
block.http: addr: :5000 secret: asecretforlocaldevelopment debug: addr: localhost:5001
-
Add a
tls
block for the server's self-signed certificates:http: addr: :5000 secret: asecretforlocaldevelopment debug: addr: localhost:5001 tls: certificate: /go/src/github.com/docker/distribution/certs/domain.crt key: /go/src/github.com/docker/distribution/certs/domain.key
You provide the paths to the certificates in the container. If you want two-way authentication across the layer, you can add an optional
clientcas
section. -
Save and close the file.
Build and run your registry image
-
Build your registry image.
$ docker build -t secure_registry .
-
Run your new image.
$ docker run -p 5000:5000 secure_registry:latest time="2015-04-12T03:06:18.616502588Z" level=info msg="endpoint local-8082 disabled, skipping" environment=development instance.id=bf33c9dc-2564-406b-97c3-6ee69dc20ec6 service=registry time="2015-04-12T03:06:18.617012948Z" level=info msg="endpoint local-8083 disabled, skipping" environment=development instance.id=bf33c9dc-2564-406b-97c3-6ee69dc20ec6 service=registry time="2015-04-12T03:06:18.617190113Z" level=info msg="using inmemory blob descriptor cache" environment=development instance.id=bf33c9dc-2564-406b-97c3-6ee69dc20ec6 service=registry time="2015-04-12T03:06:18.617349067Z" level=info msg="listening on :5000, tls" environment=development instance.id=bf33c9dc-2564-406b-97c3-6ee69dc20ec6 service=registry time="2015-04-12T03:06:18.628589577Z" level=info msg="debug server listening localhost:5001" 2015/04/12 03:06:28 http: TLS handshake error from 172.17.42.1:44261: remote error: unknown certificate authority Watch the messages at startup. You should see that `tls` is running.
-
Use
curl
to verify that you can connect overhttps
.$ curl -v https://localhost:5000 * Rebuilt URL to: https://localhost:5000/ * Hostname was NOT found in DNS cache * Trying 127.0.0.1... * Connected to localhost (127.0.0.1) port 5000 (#0) * successfully set certificate verify locations: * CAfile: none CApath: /etc/ssl/certs * SSLv3, TLS handshake, Client hello (1): * SSLv3, TLS handshake, Server hello (2): * SSLv3, TLS handshake, CERT (11): * SSLv3, TLS alert, Server hello (2): * SSL certificate problem: self signed certificate * Closing connection 0 curl: (60) SSL certificate problem: self signed certificate More details here: http://curl.haxx.se/docs/sslcerts.html
Configure Nginx with a v1 and v2 registry
This sections describes how to user docker-compose
to run a combined version
1 and version 2.0 registry behind an nginx
proxy. The combined registry is
accessed at localhost:5000
. If a docker
client has a version less than 1.6,
Nginx will route its requests to the 1.0 registry. Requests from newer clients
will route to the 2.0 registry.
This procedure uses the same distribution
directory you created in the last
procedure. The directory includes an example compose
configuration.
Install Docker Compose
-
Open a new terminal on the host with your
distribution
directory. -
Get the
docker-compose
binary.$ sudo wget https://github.com/docker/compose/releases/download/1.1.0/docker-compose-`uname -s`-`uname -m` -O /usr/local/bin/docker-compose
This command installs the binary in the
/usr/local/bin
directory. -
Add executable permissions to the binary.
$ sudo chmod +x /usr/local/bin/docker-compose
Do some housekeeping
-
Remove any previous images.
$ docker rmi -f $(docker images -q -a )
This step is a house keeping step. It prevents you from mistakenly picking up an old image as you work through this example.
-
Edit the
distribution/cmd/registry/config.yml
file and remove thetls
block.If you worked through the previous example, you'll have a
tls
block. -
Save any changes and close the file.
Configure SSL
-
Change to the
distribution/contrib/compose/nginx
directory.This directory contains configuration files for Nginx and both registries.
-
Use SSL to generate some self-signed certificates.
$ openssl req \ -newkey rsa:2048 -nodes -keyout domain.key \ -x509 -days 365 -out domain.crt
This command prompts you for basic information it needs to create certificates.
-
Edit the
Dockerfile
and add the following lines.COPY domain.crt /etc/nginx/domain.crt COPY domain.key /etc/nginx/domain.key
When you are done, the file looks like the following.
FROM nginx:1.7 COPY nginx.conf /etc/nginx/nginx.conf COPY registry.conf /etc/nginx/conf.d/registry.conf COPY docker-registry.conf /etc/nginx/docker-registry.conf COPY docker-registry-v2.conf /etc/nginx/docker-registry-v2.conf COPY domain.crt /etc/nginx/domain.crt COPY domain.key /etc/nginx/domain.key
-
Save and close the
Dockerfile
file. -
Edit the
registry.conf
file and add the following configuration.ssl on; ssl_certificate /etc/nginx/domain.crt; ssl_certificate_key /etc/nginx/domain.key;
This is an
nginx
configuration file. -
Save and close the
registry.conf
file.
Build and run
-
Go up to the
distribution/contrib/compose
directoryThis directory includes a single
docker-compose.yml
configuration.nginx: build: "nginx" ports: - "5000:5000" links: - registryv1:registryv1 - registryv2:registryv2 registryv1: image: registry ports: - "5000" registryv2: build: "../../" ports: - "5000"
This configuration builds a new nginx
image as specified by the
nginx/Dockerfile
file. The 1.0 registry comes from Docker's official public
image. Finally, the registry 2.0 image is built from the
distribution/Dockerfile
you've used previously.
-
Get a registry 1.0 image.
$ docker pull registry:0.9.1
The Compose configuration looks for this image locally. If you don't do this step, later steps can fail.
-
Build
nginx
, the registry 2.0 image, and$ docker-compose build registryv1 uses an image, skipping Building registryv2... Step 0 : FROM golang:1.4 ... Removing intermediate container 9f5f5068c3f3 Step 4 : COPY docker-registry-v2.conf /etc/nginx/docker-registry-v2.conf ---> 74acc70fa106 Removing intermediate container edb84c2b40cb Successfully built 74acc70fa106
The commmand outputs its progress until it completes.
-
Start your configuration with compose.
$ docker-compose up Recreating compose_registryv1_1... Recreating compose_registryv2_1... Recreating compose_nginx_1... Attaching to compose_registryv1_1, compose_registryv2_1, compose_nginx_1 ...
-
In another terminal, display the running configuration.
$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES a81ad2557702 compose_nginx:latest "nginx -g 'daemon of 8 minutes ago Up 8 minutes 80/tcp, 443/tcp, 0.0.0.0:5000->5000/tcp compose_nginx_1 0618437450dd compose_registryv2:latest "registry cmd/regist 8 minutes ago Up 8 minutes 0.0.0.0:32777->5000/tcp compose_registryv2_1 aa82b1ed8e61 registry:latest "docker-registry" 8 minutes ago Up 8 minutes 0.0.0.0:32776->5000/tcp compose_registryv1_1
Explore a bit
-
Check for TLS on your
nginx
server.$ curl -v https://localhost:5000 * Rebuilt URL to: https://localhost:5000/ * Hostname was NOT found in DNS cache * Trying 127.0.0.1... * Connected to localhost (127.0.0.1) port 5000 (#0) * successfully set certificate verify locations: * CAfile: none CApath: /etc/ssl/certs * SSLv3, TLS handshake, Client hello (1): * SSLv3, TLS handshake, Server hello (2): * SSLv3, TLS handshake, CERT (11): * SSLv3, TLS alert, Server hello (2): * SSL certificate problem: self signed certificate * Closing connection 0 curl: (60) SSL certificate problem: self signed certificate More details here: http://curl.haxx.se/docs/sslcerts.html
-
Tag the
v1
registry image.$ docker tag registry:latest localhost:5000/registry_one:latest
-
Push it to the localhost.
$ docker push localhost:5000/registry_one:latest
If you are using the 1.6 Docker client, this pushes the image the
v2
registry. -
Use
curl
to list the image in the registry.$ curl -v -X GET http://localhost:32777/v2/registry_one/tags/list * Hostname was NOT found in DNS cache * Trying 127.0.0.1... * Connected to localhost (127.0.0.1) port 32777 (#0) > GET /v2/registry_one/tags/list HTTP/1.1 > User-Agent: curl/7.36.0 > Host: localhost:32777 > Accept: */* > < HTTP/1.1 200 OK < Content-Type: application/json; charset=utf-8 < Docker-Distribution-Api-Version: registry/2.0 < Date: Tue, 14 Apr 2015 22:34:13 GMT < Content-Length: 39 < {"name":"registry1","tags":["latest"]} * Connection #0 to host localhost left intact
This example refers to the specific port assigned to the 2.0 registry. You saw this port earlier, when you used
docker ps
to show your running containers.