Saturday, 9 March 2019

Configure a Private Docker Registry on CentOS 7

Configure a Private Docker Registry on CentOS 7

Docker creates containers from images. These images are provided by Docker Hub, a centralized public registry that contains many official and unofficial images of almost every software in the world. However, there are situations, when we required to configure our on-premises Private Docker Registry to create and share custom docker images amongst our organizational units.

Private Docker Registry has many advantages vs Docker Hub, some of them are:

  • Since, the Docker Registry is located on premises, therefore it increases availability and speed.
  • Organization’s private images are kept within the Organizaion.
  • Provides user authentication to restrict unauthorized access.

In this article, we will configure a Private Docker Registry on CentOS 7 for our on-premises Docker hosts.

Here, we are using the Docker Engine CE to configure a Private Docker Registry. Therefore,  it is advised that you should read Docker Deep Dive for some basic to advance level understanding of Docker technology.


Table of Contents:


System Specification:

We have provisioned a CentOS 7 virtual machine with following specifications:

  • Hostname -
  • IP Address -
  • Operating System - CentOS 7.6
  • Docker Version - Docker CE 18

Note: Docker CE must be installed already on this server. You can follow our previous article Install Docker CE on an Offline CentOS 7 Machine.


Configure TLS for Private Docker Registry:

We are planning to secure our Private Docker Registry with user authentication. Therefore, we are required to configure TLS (Transport Layer Security) first as a prerequisite for user authentication.

If you have configured a Certificate Authority (CA) for you network, then you can generate a Certificate Signing Request (CSR) and get your CSR signed by that CA (Certificate Authority).

However, for the sake of simplicity, we will generate a self-signed certificate in this article and import it in Docker hosts.

Connect to Docker host: and run following command to generate a self-signed digital certificate.

[root@docker-01 ~]# mkdir -p /opt/docker/containers/docker-registry/certs [root@docker-01 ~]# openssl req > -newkey rsa:2048 \ > -nodes -sha256 \ > -x509 -days 365 \ > -keyout /opt/docker/containers/docker-registry/certs/docker-registry.key \ > -out /opt/docker/containers/docker-registry/certs/docker-registry.crt Generating a 2048 bit RSA private key ........................................................................+++ ........................+++ writing new private key to 'docker-registry.key' ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [XX]:PK State or Province Name (full name) []:Sindh Locality Name (eg, city) [Default City]:Karachi Organization Name (eg, company) [Default Company Ltd]:Ahmer's SysAdmin Recipes Organizational Unit Name (eg, section) []:ITLAB Common Name (eg, your name or your server's hostname) [] Email Address []

We have generated a self-signed digital certificate for our Private Docker Registry service. Hold it for a while, and we will use it later while creating the registry container for our Private Docker Registry.


Configure Basic HTTP Authentication for Private Docker Registry:

We create a directory and then create a passwd file therein. we will mount this directory on registry container to implement basic HTTP authentication for our Private Docker Registry.

[root@docker-01 ~]# mkdir -p /opt/docker/containers/docker-registry/auth [root@docker-01 ~]# docker run \ > --entrypoint htpasswd \ > registry -Bbn docker_user 123 > /opt/docker/containers/docker-registry/auth/htpasswd


Create a Directory to persist Private Docker Registry Data:

Create a directory on Docker host. We will mount this directory in registry container and it will hold all data pertains to our Private Docker Registry.

[root@docker-01 ~]# mkdir /opt/docker/containers/docker-registry/registry

By detaching this directory from registry container, we can easily reuse it with other containers derived from registry image. Therefore, if we remove our container, it won’t destroy the data within our Private Docker Registry.


Create a Private Docker Registry Container on CentOS 7:

Pull registry image from Docker Hub.

[root@docker-01 certs]# docker pull registry Using default tag: latest latest: Pulling from library/registry c87736221ed0: Pull complete 1cc8e0bb44df: Pull complete 54d33bcb37f5: Pull complete e8afc091c171: Pull complete b4541f6d3db6: Pull complete Digest: sha256:3b00e5438ebd8835bcfa7bf5246445a6b57b9a50473e89c02ecc8e575be3ebb5 Status: Downloaded newer image for registry:latest

Create a container for Private Docker Registry.

[root@docker-01 ~]# docker run -d \ > --name docker-registry \ > --restart=always \ > -p 5000:5000 \ > -v /opt/docker/containers/docker-registry/registry:/var/lib/registry \ > -v /opt/docker/containers/docker-registry/auth:/auth \ > -e "REGISTRY_AUTH=htpasswd" \ > -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \ > -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \ > -v /opt/docker/containers/docker-registry/certs:/certs \ > -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/docker-registry.crt \ > -e REGISTRY_HTTP_TLS_KEY=/certs/docker-registry.key \ > registry c1bf649e8277bc39133ab40c6338b3f07ea88f30628bb91060f33b77b3aeee0c


Use Private Docker Registry on Docker Hosts:

We are adding the Private Docker Registry on the same Docker host on which we have created the registry container.

Add IP Address of Private Docker Registry to Local DNS resolver of Docker host.

[root@docker-01 ~]# cat >> /etc/hosts << EOF > docker-registry > EOF

Install digital security certificate on Docker host as follow:

[root@docker-01 ~]# mkdir -p /etc/docker/certs.d/ [root@docker-01 ~]# cp /opt/docker/containers/docker-registry/certs/docker-registry.crt /etc/docker/certs.d/

Pull an image from Docker Hub. We will later push this image to our Private Docker Registry.

[root@docker-01 ~]# docker pull busybox Using default tag: latest latest: Pulling from library/busybox 697743189b6d: Pull complete Digest: sha256:061ca9704a714ee3e8b80523ec720c64f6209ad3f97c0ff7cb9ec7d19f15149f Status: Downloaded newer image for busybox:latest

Create another tag for busybox image, so we can push it into our Private Docker Registry.

[root@docker-01 ~]# docker tag busybox:latest

Login to using docker command.

[root@docker-01 ~]# docker login Username: docker_user Password: WARNING! Your password will be stored unencrypted in /root/.docker/config.json. Configure a credential helper to remove this warning. See Login Succeeded

Push busybox image to Private Docker Registry.

[root@docker-01 ~]# docker push The push refers to repository [] adab5d09ba79: Pushed latest: digest: sha256:4415a904b1aca178c2450fd54928ab362825e863c0ad5452fd020e92f7a6a47e size: 527

List locally available images of busybox.

[root@docker-01 ~]# docker images | grep busybox busybox latest d8233ab899d4 3 weeks ago 1.2MB latest d8233ab899d4 3 weeks ago 1.2MB

You can see that busybox image is available from two different Docker Registries.

We can push as many images as we like into our Private Docker Registry by using the same procedure.

We have successfully configured a Private Docker Registry on CentOS 7.


  1. I followed the steps but I am unable to Login to the Docker Registry. I have turned off firewalld but it still does not connect.
    Command: docker login
    The error message is: "Error response from daemon: Get dial tcp connect: connection refused" Any ideas? CentOS 7.6.1810 (Core)

    1. Hi,
      It looks you may have miss some steps. Because above article is tested on the same version of CentOS and working fine for me.

    2. Hi,
      I finally got it working. I found a type-o with the certificate and key names. They are generated using and "_" (docker_registry.key, docker_registry.crt) but referenced with a "-" (docker-registry.key, docker-registry.crt) when creating the private container.
      Thank you for this article as well as the linked one "Install Docker CE on an Offline CentOS 7 Machine." Your article and my mistakes help me learn a lot as I'm new to linux and docker.

  2. Hi,
    thanks for the guide, I was able to work with the registry from the host machine. However, when I try to $ docker login :5000 from a remote Windows machine, I get the next error after providing credentials:

    Error response from daemon: Get https://:5000/v2/: x509: cannot validate certificate for because it doesn't contain any IP SANs.

    Already tried to copy and import the certificate we created, but it didn't help. Could you please advice me on this issue?

    1. Hi,
      The SAN stands for "SubjectAltName".

      This error occurs when we create the TLS certificate using the hostname, while accessing it by the IP address.

      As a workaround, you can configure the name resolution for your registry server.