In this post I will go over the installation of Docker Registry with Basic Authentication and over SSL/TLS (self-signed cert for demonstration purposes). I will also do this on Docker for Mac, which has some interesting things to note.

Let me start by saying that you can use the Docker Hub which is a freely available Hosted registry, but there may be instances where you want to host your own registry to control where your images are being stored, you can also opt to use the commercial Docker Trusted Registry, but I will go over the free open-source Registry.

Create project structure
Password file to support Basic Auth
Certificates to support TLS
Location to store the images
Create Docker Registry container
Using the Registry
Registry API

Create project structure

Password file to support Basic Auth

Let’s create a username and password

Certificates to support TLS

Create a root CA key, which will sign the actual certificates

Create root CA certificate which will need to be installed on the systems that will use the Registry

Now that you have a CA, you can sign certificates.

Create a key for the Registry system

Create a Certificate Signing Request (CSR) for the CA to sign

Finally have the root CA sign the CSR

Location to store the images

The tree structure should look like below, having the data folder be the image repository

Create Docker Registry container

Run your container using docker command

Or even better, use docker-compose:

Start up container based on docker-compose.yml

See it running

At this point the Docker Registry is running

Using the Registry

Download an image from Docker Hub (or you can test with your own images built from Dockerfile)

Tag the image to point to your new Registry

Push image to your Registry (see failure due to ‘unknow CA authority’)

At this point, you need to add the root CA cert to your trusted certificates.
On the machine that will pull or push to the registry, you will need to install the rootCA.crt CA certificate created earlier:

On the Mac, you are probably using Docker for Mac, which actually runs a small hypervisor xhyve that virtualizes the docker engine. That means we need to place the rootCA.crt CA certificate inside the xhyve VM running the Docker Engine. There is no simple way of doing it and I am using the following method (which must be done everytime you restart the Docker service).

Now let’s try to Push the image to the Registry again

Good, we are getting somewhere, TLS is working, and it now asks for Authentication
Authenticate to the Docker Registry

Now let’s successfully push our image

At this point you can share your Docker image, or incorporate into a development or integration workflow by pulling the image
From any Docker engine system:

Registry API

You can use the Docker Registry API https://docs.docker.com/registry/spec/api/ to interact with your Registry.

For example to see a catalog of your images: