Install a private docker registry from scratch

This is a tutorial explaining how to install a private docker registry from scratch. It will include remote access with user authentication.


This tutorial uses an Ubuntu Server 16.04 LTS base installation.

Installing Docker

The registry will be a docker container itself. Thus to let it run we need to install docker.

Let’s prepare the environment. Update ubuntu packages and ca certificates:

$ sudo apt-get update
$ sudo apt-get install apt-transport-https ca-certificates

Add a new GPG key:

$ sudo apt-key adv — keyserver hkp:// — recv-keys 58118E89F3A912897C070ADBF76221572C52609D

Add the docker registry to the apt sources:

$ sudo vi /etc/apt/sources.list.d/docker.list

and enter:

deb ubuntu-xenial main

than save and exit vi.

Update packages list one more time:

$ sudo apt-get update

Install the kernel packages:

$ sudo apt-get install -y linux-image-extra-$(uname -r) linux-image-extra-virtual

Install docker!

$ sudo apt-get install -y docker-engine

Start the docker daemon

$ sudo service docker start

Create a docker group so that you don’t have to use sudo in front of every docker command

sudo groupadd docker
sudo usermod -aG docker $USER

Logout and login.

At this point you have docker installed and restarting automatically at reboot.

Install docker-compose

docker-compose will come very handy when running your container, so let’s install it

$ sudo apt-get install -y docker-compose

Registry installation

As said before the docker registry can be installed as a docker container.

Moreover we will enable TSL by letting the registry use a certificate and key couple.

Put your certificate and key in a well known directory: for example the certificate under <USER_HOME>/certs/domain.crt and the key under <USER_HOME>/certs/domain.key.

Now let’s prepare the file with usernames and passwords of the allowed clients.

Create the directory <USER_HOME>/auth, then run:

$ docker run — entrypoint htpasswd registry:2 -Bbn <USERNAME> PASSWORD >> auth/htpasswd

You will have to run it every time you need to add a new user.

In order to have access to the registry data from outside the container, we will map a directory to a container volume, so create it in advance at the path <USER_HOME>/data.

We will run the container using docker-compose, this tool needs its configuration file, create in the user home a new file called docker-compose.yml and put the following lines in it:

restart: always
image: registry:2
- 5000:5000
REGISTRY\_HTTP\_TLS\_KEY: <USER\_HOME>/certs/domain.key
REGISTRY\_AUTH: htpasswd
- <USER\_HOME>/data:/var/lib/registry
- <USER\_HOME>/certs:/certs
- <USER\_HOME>/auth:/auth

Finally we can run our registry! Run this:

$ docker-compose up -d

This will run a docker registry available on port 5000, so be sure to have the port open to the network.

Test registry installation

From an external machine with docker installed, try logging in your newly created registry typing

$ docker login

Then insert your username and password as created in the step above.

If everything is ok, you will see the login ok message.