How to Set Up a Private Docker Registry with TLS and Authentication
Run a private container registry with the official registry image on any Docker host, with HTTPS, password authentication and basic maintenance.
A private registry lets you push and pull your own container images without sending them to a public service. This guide sets one up with the official registry image (the CNCF Distribution project) on any current Linux host that runs Docker Engine, serves it over HTTPS with a real certificate, and protects it with a username and password. At the end you will be able to run docker login registry.example.com from any machine and push images to your own server.
Older tutorials built this on CoreOS Container Linux, which has been discontinued; its maintained drop-in successor is Flatcar Container Linux, and the docker run commands below work there as well as on Ubuntu, Debian, AlmaLinux or Rocky Linux.
Requirements
- A server with Docker Engine installed and a user that may run
docker(the examples usesudo). - A DNS name that points to the server. The examples use
registry.example.com. - A TLS certificate and private key for that name from a certificate authority, for example Let's Encrypt. You need the full chain (your certificate followed by the intermediate certificate) in one file.
- TCP port 443 open in your firewall.
- Enough disk space for your images. Every pushed layer is stored on this server.
Docker clients refuse to talk to a remote registry over plain HTTP unless each client is explicitly reconfigured, and the registry's password authentication sends credentials in HTTP headers. Treat TLS as mandatory, not optional.
Step 1: Create the directories
Keep the image data, the certificate and the password file in separate directories on the host so that they survive when the container is replaced.
sudo mkdir -p /srv/registry/data /srv/registry/certs /srv/registry/auth
Step 2: Install the certificate
Copy the full-chain certificate and the private key into the certs directory. If your certificate authority gave you a separate intermediate certificate, concatenate your certificate and the intermediate into one file first. With a Let's Encrypt certificate obtained by Certbot, the two files are already in the right form:
sudo cp /etc/letsencrypt/live/registry.example.com/fullchain.pem /srv/registry/certs/domain.crt
sudo cp /etc/letsencrypt/live/registry.example.com/privkey.pem /srv/registry/certs/domain.key
sudo chmod 600 /srv/registry/certs/domain.key
Step 3: Create the password file
The registry's built-in authentication reads an htpasswd file. Only bcrypt hashes are accepted; entries with any other hash type are ignored. You do not need to install Apache tools on the host, because the httpd image contains the htpasswd program. The -B option selects bcrypt:
sudo docker run --rm --entrypoint htpasswd httpd:2 -Bbn deploy 'choose-a-long-password' | sudo tee /srv/registry/auth/htpasswd
To add a second user, run the same command with another name and append the output with sudo tee -a. The command leaves the password in your shell history; clear that entry afterwards.
Step 4: Start the registry
Run the current major version of the image, registry:3. The environment variables make the registry listen on port 443 with your certificate and require a login for every request:
sudo docker run -d \
--name registry \
--restart=always \
-p 443:443 \
-v /srv/registry/data:/var/lib/registry \
-v /srv/registry/certs:/certs:ro \
-v /srv/registry/auth:/auth:ro \
-e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
-e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
-e REGISTRY_AUTH=htpasswd \
-e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
-e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
registry:3
--restart=always brings the registry back after a reboot or a crash. Every setting in the registry's configuration file can be overridden this way: the variable name is REGISTRY_ followed by the configuration path in upper case with underscores between the levels.
The same setup with Docker Compose
If the host has the Compose plugin, you can describe the container in a file instead. Save this as /srv/registry/compose.yaml:
services:
registry:
image: registry:3
restart: always
ports:
- "443:443"
environment:
REGISTRY_HTTP_ADDR: 0.0.0.0:443
REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
REGISTRY_HTTP_TLS_KEY: /certs/domain.key
REGISTRY_AUTH: htpasswd
REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm
REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
volumes:
- /srv/registry/data:/var/lib/registry
- /srv/registry/certs:/certs:ro
- /srv/registry/auth:/auth:ro
Start it from that directory. Use either this or the docker run command, not both, because only one container can bind port 443.
cd /srv/registry
sudo docker compose up -d
Step 5: Log in and push an image
Check that the container is running and look at its log for certificate or password-file errors:
sudo docker ps --filter name=registry
sudo docker logs registry
From your workstation or another server, log in with the user you created. Docker asks for the password:
docker login registry.example.com
Pull a small public image, tag it with your registry's name, and push it:
docker pull alpine:latest
docker tag alpine:latest registry.example.com/alpine:latest
docker push registry.example.com/alpine:latest
Remove the local copies and pull the image back from your registry to prove the round trip:
docker image rm alpine:latest registry.example.com/alpine:latest
docker pull registry.example.com/alpine:latest
The image name always starts with the registry's host name. If you publish the registry on a port other than 443, the port is part of the name too, for example registry.example.com:5000/alpine:latest.
Maintenance
Renewing the certificate
The registry reads the certificate when it starts. After each renewal, copy the new files over domain.crt and domain.key as in step 2 and restart the container:
sudo docker restart registry
With Certbot you can put those copy and restart commands into a deploy hook so they run automatically after a successful renewal.
Changing users
The htpasswd file is loaded once at startup and is not reloaded. After you add, remove or change a user, restart the container. If the file is invalid the registry logs an error and refuses to start, so check docker logs registry after every change.
Updating the registry
Pull the newer image and recreate the container. The data in /srv/registry/data is untouched.
sudo docker pull registry:3
sudo docker stop registry
sudo docker rm registry
Then run the docker run command from step 4 again. With Compose, sudo docker compose pull followed by sudo docker compose up -d does the same.
Freeing disk space
Deleting images through the API is disabled by default; it is controlled by the storage.delete.enabled setting (REGISTRY_STORAGE_DELETE_ENABLED=true as an environment variable). Removing a manifest does not free space by itself. Layers that nothing references any more are removed by the registry garbage-collect command, which takes the path of the configuration file and supports --dry-run to show what would be removed. Run it only while the registry is stopped or in read-only mode: a push that arrives during garbage collection can lose its layers and leave a corrupt image.
Frequently asked questions
Can the registry get its own Let's Encrypt certificate?
Yes. The configuration has an http.tls.letsencrypt section with a cache file, a contact e-mail address and a list of host names. The registry must be reachable from the internet on port 443 for this to work, and you should always set the host list so that the registry does not request certificates for arbitrary names sent by clients.
Can I use a self-signed certificate?
You can, but every Docker host that talks to the registry must then be told to trust that certificate, and other tools need the same treatment. A certificate from a public certificate authority avoids that work on every client and is the simpler choice for a server with a public DNS name.
Can I put the registry behind a reverse proxy or load balancer?
Yes. The proxy must pass the Host, X-Forwarded-Proto and X-Forwarded-For headers through unchanged, otherwise the registry may redirect clients to an internal address or to plain HTTP. An unauthenticated request to /v2/ correctly returns status 401, so a health check has to treat 401 as healthy or check / instead. If several registry instances share the load, they must all use the same storage backend and the same http.secret value.
Where are the images stored?
Inside the container the registry writes to /var/lib/registry. In this setup that path is the host directory /srv/registry/data, which is the only thing you need to back up besides the certificate and the password file. The registry also supports object storage backends through its storage driver configuration.