Deploying a Private Docker Registry

Private Docker Registry with SSL and basic auth, includes a docker-compose.yml file

Published: 11/Apr/2016

This is a short summary of Deploying a registry server from the official Docker documentation


  • Private repositories require an SSL certificate (ideally signed by a CA, otherwise self-signed)
  • Additionally, the repo is secured by http basic auth

Example docker-compose.yml

  container_name: registry
  restart: always
  image: registry:2
    - 5000:5000
    - "/storage/registry/data:/var/lib/registry"
    - "/storage/registry/certs:/certs"
    - "/storage/registry/auth:/auth"
    - REGISTRY_AUTH=htpasswd
    - REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd

This requires a /storage/registry directory on the Docker host, with the following sub-directories

  • data/: Contain images, can be empty on first run
  • certs/: Should contain both public and private keys for the SSL certificate of the (wildcard) domain
  • auth/: contain a file htpasswd with basic auth credentials

Creating the htpasswd file

Initialy, I tried using apache's htpasswd -c tool to create the htpasswd file. For some reason the created file didn't work (auth failed) with the docker registry.

So instead, follow the guide, and use the included htpasswd entrypoint:

docker run --entrypoint htpasswd registry:2 -Bbn myusername mypasswd > htpasswd

This will create a valid htpasswd file that you can copy to the docker host, in the auth/ directory.

Running the server

Simply run:

docker-compose up

Loging in

Before you can push images to a private registry, you need to login from your client machine.

Use the following command:

docker login

Pushing images

After loging in, you can push images to the private registry like this:

docker pull ubuntu
docker tag ubuntu
docker push

Using alternative backend storage drivers

The earlier docker-compose.yml uses standard host-based storage. This works as long as the storage volume is limited, but you may have good reasons to an alternative storage backend such as Amazon S3, Azure, Swift, Google Cloud Storage, etc.

For more information, click here

Further reading