In this tutorial we are going to learn about Docker registry and how to setup your own private registry with self-sign certificates.

I hope you have read previous posts on docker basics and it’s concepts.

What is Docker Registry?

A registry is a storage and content delivery system, holding named Docker images, available in different tagged versions.

There are to types of Registry:

How it’s works?

When you run docker run -it centos bash or docker pull centos command, it’s first checks the image exists locally or not, if not then it pulls from the Docker hub. imagine if you are pulling image on multiple servers, you will have to download the image from docker hub, multiple times. this process will take huge time if your internet connection is slow, So to avoid this we can build our private repository where we can store our private images. that is use case one but other use like you tightly control where your images are being stored, fully own your images distribution pipeline.

Setup Private Registry

There are two ways of setting up your private registry:

  1. Using self-sign certificates, Quick and dirty way
  2. Register Certificates for your domain: For production setup

Method 1

Let’s try with self-sign certificates

  1. Create directory for hosting registry and registry storage.
mkdir /opt/docker-registry
cd /opt/docker-registry/
mkdir data
mkdir certs
  1. Generate self-sign certificates
openssl req -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key -x509 -days 365 -out certs/domain.crt
  1. Start your registry
docker run -d -p 5000:5000 --restart=always \
   --name registry -v $PWD/data:/var/lib/registry \
   -v $PWD/certs:/certs -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
   -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key registry:2


We can test from same host but since we are using self-sign certificates, we need to install in docker client, for that you need to copy certificate file in /etc/docker/conf.d/:5000/ca.crt

let’s assume that your FQDN is

Instaling Linux client certificates

mkdir /etc/docker/certs.d/
cp certs/domain.crt /etc/docker/certs.d/\:5000/ca.crt

Now try to push any local image to your registry server

docker images

Copy any image id from about command output

docker tag <IMAGE_ID>
docker push

Bingo !!!

Congrantulation, you just setup your private registry.

Instaling Mac OS client certificates

mkdir /etc/docker/certs.d/
cp domain.crt /etc/docker/certs.d/\:5000/ca.crt
sudo security add-trusted-cert -d \
   -r trustRoot -k /Library/Keychains/System.keychain \

Now you can push/pull from your registry server.

Method 2

Following things require to run in production :

As you can see in above picture, you can use Load Balanacer like HAproxy, Nginx or ELB ( in AWS ) which handle SSL and proxy request to your registry server.