Latest

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 Containerization technology.

Configure a Private Docker Registry on CentOS 7

Table of Contents:

 

System Specification:

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

  • Hostname - docker-01.example.com
  • IP Address - 192.168.116.140/24
  • 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 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: docker-01.example.com and run following command to generate a self-signed digital certificate.

# mkdir -p /opt/docker/containers/docker-registry/certs
# 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) []:docker-registry.example.com
Email Address []:root@docker-01.example.com

We have generated a self-signed digital certificate. 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 Docker Registry.

# mkdir -p /opt/docker/containers/docker-registry/auth
# docker run \
> --entrypoint htpasswd \
> registry -Bbn docker_user 123 > /opt/docker/containers/docker-registry/auth/htpasswd

 

Create a Directory to persist Registry Container 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.

# 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 Docker Registry Container on CentOS 7:

Pull registry image from Docker Hub.

# 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.

# 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 docker-01.example.com on which we have created the registry container.

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

# cat >> /etc/hosts << EOF
> 172.17.0.2 docker-registry.example.com docker-registry
> EOF

Install digital security certificate on Docker host as follow:

# mkdir -p /etc/docker/certs.d/docker-registry.example.com:5000
# cp /opt/docker/containers/docker-registry/certs/docker-registry.crt /etc/docker/certs.d/docker-registry.example.com:5000/ca.crt

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

# 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.

# docker tag busybox:latest docker-registry.example.com:5000/busybox

Login to docker-registry.example.com using docker command.

# docker login docker-registry.example.com:5000
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
https://docs.docker.com/engine/reference/commandline/login/#credentials-store

Login Succeeded

Push busybox image to Private Docker Registry.

# docker push docker-registry.example.com:5000/busybox
The push refers to repository [docker-registry.example.com:5000/busybox]
adab5d09ba79: Pushed
latest: digest: sha256:4415a904b1aca178c2450fd54928ab362825e863c0ad5452fd020e92f7a6a47e size: 527

List locally available images of busybox.

# docker images | grep busybox
busybox                                    latest              d8233ab899d4        3 weeks ago         1.2MB
docker-registry.example.com:5000/busybox   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 Docker Registry by using the same procedure.

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

If you find this article useful? Consider supporting us by Buy Me A Coffee


6 comments:

  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 docker-registry.example.com:5000
    The error message is: "Error response from daemon: Get https://docker-registry.example.com:5000/v1/users/: dial tcp 192.168.1.56:5000: connect: connection refused" Any ideas? CentOS 7.6.1810 (Core)

    ReplyDelete
    Replies
    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.

      Delete
    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.

      Delete
  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?

    ReplyDelete
    Replies
    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.

      Delete

© 2022 CentLinux. All Rights Reserved.