Gotchas / Tips Creating Your Own Private Docker Registry With Self Signed Certificate

1 Star2 Stars3 Stars4 Stars5 Stars (No Ratings Yet)

Creating your own private Docker Registry using a Self Signed Certificate

Creating your own private Docker Registry without authentication, authorization or SSL can be a simple process, but creating a private Docker Registry with SSL support, authentication i.e. Tokens, LDAP, etc.. can be a bit more complicated.

Below I will show you in detail how to create your own private Docker Registry(v2), as well as a number of issues and workarounds. to note, all tests ware completed / tested o ubuntu 17.04(zesty) OS.

Creating your own Docker Registry, requiters addressing a number of issues outlined below. Most of them are addressed later in this article, and some will be addressed in an upcoming article.

Securing your Docker Private Registry Instance(s), includes

  • Option 1: Configure Your own CA with your SSL Certificate
  • Option 2: Buy an SSL Certificate from one of the public providers

Front end your Docker Private Registry with a secure device (can be a Docker instance)

  • Use Simple SSH port forwarding
  • Use pre-configured Nginx Containers to front end your Docker Registry
  • Create your own Nginx Container to protect your Docker Registry
  • Use a hardware Load Balancer such as F5 to front-end and protect your Docker Registry

Authentication and Authorization

  • Use a pre-configured Docker container with all the Docker Registry + LDAP configurations
  • Use a Docker Token service for Authentication and Authorization (works in newer Docker versions)

Other options are: Use a pre-configured GUI Manager to Manage your full Docker registry. Complete packages – include Docker Registry, Authentication and Authorization, Managed with a nice web UI(GUI).
Pre configured Docker Authentication GUI Managers are listed below

Even more options are, to use something like Rancher and Portainer more details is available here, they do much more then just managing a local registry.

Note: Before creating your own Docker Registry, you will need to install the Docker binary application(s). to do so follow the steps outlined here

Setting / configuring your Docker Proxy settings

Note: You can skip this step if you are not using a proxy i.e. if you are not using http_proxy, https_proxy, etc…

The below configuration is an example of my /etc/systemd/system/docker.service.d/http-proxy.conf file with the proxy configuration in it.

Note: Make sure to add your local hostname, in this case its docker to your no_proxy list.
I was struggling with this for a while by not having that set. if you do not add your hostname to the no_proxy list, your docker iptables related configuration will not get properly configured, the resutls will be, not being able to access your private docker repository. to note, your localhost:5000 might still work(if no SSL is enabled), but with SSL enabled using an FQDN (like is required, which will not work otherwise.

Below are the errors you might get while pushing an image to the local registry, without adding your hostname to the no_proxy list.

Creating and Configuring your Certificates

Next, will move on creating your Certificates – this is needed for SSL communication.
There are a number of methods to use/create your own certificates, below is outlined two options.
Note You can of course use/get your SSL certificate signed by one of the public CA’s, you can then skip to the next step.

  • Manuel creating your certificate and move it in place
  • Automatically creating your certificate and move it in place, using the paulczar/omgwtfssl Docker image

For Docker to fully work using your own SSL certificate, you will also need to create your own CA.

Creating your own Certificates – The Manuel way

As mentioned above, I am using the FQDN i.e. hostname as docker I will use this for the rest of the article.

First create a CA key with a bit size of 2048 (or whatever bit length you like)

Sign your CA key

Next, Create a server / client certificate and sign with ca

First lets Generate a new server or client key.

Create the client certificate request – to be signed by CA

Note: If you like to use one of the public CA’s, the key.pem would be the file send to the public CA for signature.

Self sign the client certificate by your own CA (or send to public CA)

Now, that the certificate(s) are generated(CA and server/client), we are ready to use them.

Copy the certificate(s) to the proper locations (outlined below), the docker registry will then use / trust the new certificate(s), more is explained below.

The process above shows you how to create your certificates manually.
Next will move on to show you how to to automate this process(its your choice which direction to go).

Creating your own Certificates by Using the paulczar/omgwtfsslby Docker image

The Docker image used in automating the Certificates – credit goes to this git repository

The process below will pull the Docker image and generated the certificate(s) and key(s) (CA and Server/Client).

Initial Registry Configuration

Next will move on to, Required Docker SSL settings

Below are the the settings required to get the Docker Registry working with SSL.

Note: Additional options can be set in the registry.env(depending in the Docker version, RedHat, Ubuntu, etc), I included a small subset sample below.

Add and trust the self signed certificate(s) on your system

The next step is to add your own CA certificate to the systems trusted certificates store.

Lets create a Docker directory to store our Docker CA certificate, then lets add the certificate location to system CA trusted store.

Next, lets copy the CA certificate to the new trusted store location we just created, then run the system update, to let the system know about the new certificate.

Last, restart the Docker demon for the changes to take effect.

Note: Restarting Docker is absolutely needed, as the self signed certificate will not work without that.
Below are the errors you might get, if you do not restart the Docker demon even after you added your new SSL certificate(s).

Complete the Docker registry installation and configuration

Now, finally complete docker initial registry installation and configuration.

You can also create a DockerFile with similar options like the one below.

Then build and run the Docker registry container.

Begin using your own Docker registry

Now that the registry is up and running, we can start pushing and pulling images.

Lets pull the busybox image from the public repository.

Before we can publish/push the busybox image we now need to tag it.

Last, lets try to pull the image from our own repository.

Authentication and Authorizations

Now that our private repository is up and running, its time to discuses Docker security options.
Note: The private Docker registry configured above has no security configurations configured, i.e. you can push/pull withany Authentication required.

There are a number of options around Docker Authentication and Authorizations, from using Docker itself, using tokens, LDAP, etc, front-ending Docker with an Nginx Docker image, or front-ending Docker by using a Load Balancer like an F5 handling the security.

Below I will discuss some of the options.

Using SSH for simple Authentication

The simplest configuration, i.e. just adding Authentication in the mix can be using ssh port-forwarding.

To use that, just run the below, change the port and server names to match your configuration.

Using a Docker pre configured image for Authentication

The next option would be, building an Nginx image, or using a pre-build Nginx Docker images.
By using Nginx as the proxy(front-end) for your Docker Registry, you gain all the befits that Nginx brings to table.
I hope to update this article once available, with the full details.

The next option would be(and especially if you’re looking to utilize your own LDAP), by using one of the Docker images available on github. they include an easy way to configure, point to your own LDAP for Authentication and Authorization.

There are a number of images available on github, each with their own benefits (and weaknesses). a partial list is below.

Private Docker registry GUI Managers

Another option is, to use one of the Docker GUI managers, there are a nice few options available, each have their own strengths and weaknesses.

Below is a partial Docker Web UI/GUI manager list.

Atomic Registry – a Red-hat sponsored project

Portus – a Suse sponsored project

Harbor – a VmWare sponsored project

Shipyard Build on Docker Swarm – Composable Docker Management

Other GUI option are, to use something like Rancher and Portainer more details is available here

Disabling SSL temporarily for testing purposes

For troubleshooting purposes, you might try to disable the SSL in your registry.
Modify your DOCKER_OPTS in the /etc/default/docker Docker file like below.
Note: A docker restart will be required for the changes to take effect.

Private Docker helpful tips

Docker registry v2 searching / tag listing

Docker private registry v2, has no search endpoint, I would love to find out otherwise – please let me know in the comments below. However, their are a few other end-points available to use listed below.
Using Docker for Search in v2 will not work

Using curl will partly work

Getting the full Docker private registry listing

Getting the tag list for a specific image

Getting the manifest for a specific image

Note: You can always create your own little Python program to pull the full catalog and tags, adding to a dictionary, then manipulating that.

What was your experience creating a private Docker registry, please let me know in the comments below.

Helpful Docker registry information script

The below script will proved details about your private Docker registry packages and disk space.

A sample output is below.

You might also like
Managing docker on Ubuntu 17.04 using Rancher or Portainer
Using ZFS for Docker COW Storage layer(s) In Ubuntu 17-04

Leave a Reply

Notify of