A Secure Docker 2.0 Registry with Basic Authentication

There are many guides on web about how to run a v2 Docker Registry, including the offical documentation. However, I couldn't get a secure, password protected registry to start up after reading offical documentation. Other guides recommend using nginx as a proxy to implment basic authentication, but the offical documention discourges this.

This post will walk you through the steps necessary to set up a secure Docker Registry 2.0 with basic authentication without a proxy server.

Step 1: Read the Documentation

Read the offical documentation on deploying a v2 Docker Registry. You can skip to the end for a working example, but it's best to really understand what's going on here.

Step 2: Buy an SSL Certificate (really)

You should run your registry using a valid SSL certificate. I purchased a certificate, valid for 3 years, from SSLs.com for $14 USD last night. At less than $5 a year, it's a no brainer to do things right, even if it's just an expirament.

If you're using a CentOS/RedHat based distibution, the best place to put your private key and certificate chain is /etc/pki/tls/certs/docker-registry.

Step 3: Install Docker Compose

Install Docker Compose. We're going to use it to define our registry setup in a declaritive fashion. If you're attempting this on Windows, don't. Docker Compose doesn't work. Quit now or install Linux in a VM and keep reading.

Step 4: Create your htpasswd file

Use the registry:2 Docker image to create a Bcrypt encoded password for each user you want to have access to your private repository.

# mkdir -p /var/lib/docker-registry/auth/
# docker run --rm --entrypoint htpasswd registry:2 -Bbn username password >> /var/lib/docker-registry/auth/htpasswd

Step 5: Create a custom Registry Configuraion

Although, the documentation says you can pass environment variables, such as REGISTRY_AUTH_HTPASSWD_REALM and REGISTRY_AUTH_HTPASSWD_PATH to require basic authentication to your realm, it doesn't work. You'll have to create a custom registry config.yml to support this.

Here's a complete, working config.yml:

version: 0.1  
  level: info
    service: registry
        layerinfo: inmemory
        rootdirectory: /var/lib/registry
       realm: basic-realm
       path: /auth/htpasswd
    addr: :5000

Step 5: Create Your Docker Compose File


Before defining your registry as a docker-compose.yml file. You should create on your host:

  1. /var/lib/docker-registry/conf to hold your registry configuration
  2. /var/lib/docker-registry/data to hold persistent registry data
  3. /etc/pki/tls/certs/docker-registry containing your SSL certificate and any intermediate certificates
  4. /var/lib/docker-registry/auth to hold your htpasswd file

Create Volumes

Create your volumes that we'll map into the Docker container:

# mkdir -p /var/lib/docker-registry/auth
# mkdir -p /var/lib/docker-registry/conf
# mkdir -p /var/lib/docker-registry/data
  • /var/lib/docker-registry/auth > put your htpasswd file here
  • /var/lib/docker-registry/conf > put your config.yml here
  • /var/lib/docker-registry/data > directory for registry data

Compete docker-compose.yml

Create a docker-compose file containing the following:

  restart: always
  image: registry:2
    - 5000:5000
    REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
    REGISTRY_HTTP_TLS_KEY: /certs/domain.key
    - /var/lib/docker-registry/conf:/etc/docker/registry
    - /var/lib/docker-registry/data:/var/lib/registry
    - /etc/pki/tls/certs/docker-registry:/certs:ro
    - /var/lib/docker-registry/auth:/auth:ro

Start Your Registry

# docker-compose up -d
comments powered by Disqus

Software Engineer living in NYC
More Detail →
  • Software Engineering
  • Full Stack
  • Java
  • Spring
  • Linux
  • MongoDB
  • Objective-C
← Back

Recent Posts