How to set up a private Docker registry?

· Category: Docker

Short answer

Deploy a private Docker registry using the official registry image. Secure it with TLS certificates and basic authentication, and configure clients to trust the registry.

Steps

  1. Run the registry container:
docker run -d -p 5000:5000 --name registry registry:2
  1. Generate TLS certificates.
  2. Enable authentication with htpasswd.
  3. Restart the registry with TLS and auth volumes mounted.

Example

docker run -d   -p 5000:5000   --name registry   -v $(pwd)/certs:/certs   -v $(pwd)/auth:/auth   -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/cert.pem   -e REGISTRY_HTTP_TLS_KEY=/certs/key.pem   -e REGISTRY_AUTH=htpasswd   -e REGISTRY_AUTH_HTPASSWD_REALM=Registry   -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd   registry:2

Login and push:

docker login myregistry:5000
docker tag myapp myregistry:5000/myapp
docker push myregistry:5000/myapp

Tips

  • Use a reverse proxy like Nginx or Traefik for production.
  • Back up the registry storage volume regularly.
  • Enable garbage collection to reclaim space from deleted images.

Common issues

  • Untrusted registry errors require adding the CA to the Docker daemon.
  • Authentication failures often stem from incorrect htpasswd formatting.
  • Pushing large layers can timeout on slow networks.