How to run a private Docker registry

Containers all the things!
Photo by Victoire Joncheray / Unsplash

Step by step

For the patient: you can follow the official documentation here with a good step-by-step to begin with. Try following the steps there.

Or, if you are just like me: just try the following commands:

mkdir registry && cd registry
mkdir auth certs storage

// replace USERNAME and PASSWORD here with credentials for your registry
docker run --entrypoint htpasswd registry:2 -Bbn "USERNAME" "PASSWORD" > auth/htpasswd

These steps worked for me using Nginx for SSL termination and LetsEncrypt for certificates.

Securing the registry

You can use letsencrypt to get a valid SSL password and secure your registry. You need to set up SSL to make it work.

After getting the certificates, they will be probably available at /etc/letsencrypt/live/yourdomain.com. So let's copy them to our registry folder:

cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem certs/docker.crt
cp /etc/letsencrypt/live/yourdomain.com/privkey.pem certs/docker.key

Copy certificates to our current directory

Running the registry

Now that SSL certificates are ready and we created a password to protect our registry, let's run it!

Note: don't forget to replace the secret string below!
export REGISTRY_HTTP_SECRET="some-very-long-random-string"

docker run --rm -d \
  -p 3000:443 \
  --name registry \
  -v $(pwd)/storage:/var/lib/registry \
  -v "$(pwd)"/auth:/auth \
  -e REGISTRY_LOG_LEVEL=debug \
  -e "REGISTRY_AUTH=htpasswd" \
  -e REGISTRY_HTTP_SECRET \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
  -v $PWD/certs:/certs \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/docker.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/docker.key \
  registry:2

Troubleshooting

Sometimes pushing a big image to your private registry will be halted mid-upload.

I was using Nginx a while ago as a reverse proxy, and that was the case for me. I had to change my settings and add the following rule to Nginx configuration: client_max_body_size 1000M;

Subscribe to darlanalv.es

Sign up now to get access to the library of members-only issues.
Jamie Larson
Subscribe