DOCKER_REGISTRY_WITH_LETS_ENCRYPT.md

Setting up a Docker Registry with Let's Encrypt TLS support

This gist describes how to set up a private Docker Registry on an AWS EC2 instance and how to secure it with TLS using a certificate by Let's Encrypt.

A Docker registry is a server side application that stores and lets you distribute Docker images. It runs in an own Docker container and the image is freely available. Let's Encrypt is a Certificate Authority that gives away TLS certificates for free.

0. Prerequisites

We require the following three items to be set up correctly before we start.

1. An EC2 instance with Docker installed
2. A domain name associated with the EC2 instance
3. The EC2 instance's VPC and Security Group have been setup to expose the ssh port and the Docker Registry port (5000/TCP) publicly.

1. Get a certificate from Let's Encrypt

1. On the EC2 instance, clone the certificate bot for obtaining the certificate from Let's Encrypt: git clone https://github.com/certbot/certbot.git
2. Run the bot with the standalone plugin (i.e., no webserver required). Substitute YOUR_DOMAIN in the examples from here on.

 ./certbot-auto certonly --standalone -d YOUR_DOMAIN --email YOUR_EMAIL_ADDRESS

This generates the following four files in /etc/letsencrypt/live/YOUR_DOMAIN

cert.pem  chain.pem  fullchain.pem  privkey.pem

into the registry container next and copy the files into i

2. Start the Docker Registry

1. Still on the EC2 instance, we will need the fullchain.pem and privkey.pem in our registry. Therefore, we create a directory /certs/ to be mounted as volume in the next step. For consistency with the Docker Registry documentation we rename the files to domain.crt and domain.key, respectively.
2. Run the registry as follows.

docker run -d -p 5000:5000 -p 443:443 \
  --restart=no \
  --name registry \
  -v /certs:/certs \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  registry:2

3. Verify the registry and TLS are working

1. On your local machine (preferrably on the EC2 instance hosting the registry), smoke test with curl https://YOUR_DOMAIN:5000. This should yield no errors.
2. Download and tag an image so that it points to the new registry: docker pull sinatra && docker tag sinatra YOUR_DOMAIN:5000/sinatra
3. Push the image to the new registry. docker push YOUR_DOMAIN:5000/sinatra. If the upload succeeds all is fine.
4. Verify by listing your registry's catalog curl -X GET https://YOUR_DOMAIN:5000/v2/_catalog.

References

• The official documentation on deploying the Docker Registry
• A less detailed guide
• Information on the certificate files obtained by the certificate bot