How to install Docker-Distribution on CentOS 7

Learn how to install Docker-Distribution on CentOS 7 with our easy-to-follow guide. Get step-by-step instructions for a Secure Docker Registry setup and configuration on your CentOS 7 system. #centlinux #linux #docker

What is Docker Registry?

Docker Registry is a content storage and delivery system, that stores different tagged versions of Docker images. Users interact with the Registry by means of a Push or Pull methods. Docker Hub is a public docker registry that provides millions of images to trillions of users. But there are scenarios, where we are required to setup a private and secure in-premises Docker Registry.

We have already configured a Private Docker Registry on CentOS 7 in our previous article by using containers technology, where we have created a Registry container by using Docker.

Now, we are using an alternate method to create a Secure Docker Registry without using containers. In this article, we will install Docker-Distribution on CentOS 7 to configure a secure registry and then test it by using it through Docker hosts.

System Specification

We have configured a CentOS 7 virtual machine with following specification.

• Hostname – dregistry-01.centlinux.com
• IP Address – 192.168.116.153/24
• Operating System – CentOS 7.6
• CPU – 3.4 Ghz (1 Core)
• Memory – 1 GB
• Storage – 40 GB

We are also using a Docker Host with following specification to test our Secure Docker Registry.

• Hostname – docker-manager-01.centlinux.com
• IP Address – 192.168.116.150/24
• Operating System – CentOS 7.6
• Docker Version – Docker Engine CE 18.09

Recommended Training: Docker Mastery: with Kubernetes +Swarm from a Docker Captain

Install Docker-Distribution on CentOS 7

Connect with dregistry-01.centlinux.com using ssh as root user.

Docker-Distribution package is available in extras yum repository.

Check the available version of Docker-Distribution package.

yum info docker-distribution

Output:

Loaded plugins: fastestmirror
Loading mirror speeds from cached hostfile
 * base: mirrors.ges.net.pk
 * extras: mirrors.ges.net.pk
 * updates: mirror1.ku.ac.th
Installed Packages
Name        : docker-distribution
Arch        : x86_64
Version     : 2.6.2
Release     : 2.git48294d9.el7
Size        : 12 M
Repo        : installed
From repo   : extras
Summary     : Docker toolset to pack, ship, store, and deliver content
URL         : https://github.com/docker/distribution
License     : ASL 2.0
Description : Docker toolset to pack, ship, store, and deliver content

Install above package with the help of yum command.

yum install -y docker-distribution

Configure Secure Docker Registry with Docker-Distribution

We are configuring a Secure Docker Registry, therefore, we have to create a SSL/TLS certificate for it.

openssl req \
-newkey rsa:2048 \
-nodes -sha256 \
-x509 -days 365 \
-keyout /etc/pki/tls/private/registry.key \
-out /etc/pki/tls/registry.crt

Output:

Generating a 2048 bit RSA private key
..............+++
.............................................................+++
writing new private key to '/etc/pki/tls/private/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) []:dregistry-01.centlinux.com
Email Address []:root@dregistry-01.centlinux.com

To restrict anonymous access, we will setup basic HTTP authentication for our Docker Registry Service. For this purpose, we need to install htpasswd utility to create a HTTP password file.

yum install -y httpd-tools

Now, create a HTTP password file as follows:

htpasswd -c -B /etc/docker-distribution/dockerpasswd ahmer

Output:

New password:
Re-type new password:
Adding password for user ahmer

We have used -B switch above to create an entry with bcrypt encryption because it is the only supported format right now, and the entries with other hash types will be ignored.

Edit config.yml configuration file in vim text editor.

vi /etc/docker-distribution/registry/config.yml

and update it as follows:

version: 0.1
log:
  fields:
    service: registry
storage:
    cache:
        layerinfo: inmemory
    filesystem:
        rootdirectory: /var/lib/registry
http:
    addr: 192.168.116.153:5000
    tls:
        certificate: /etc/pki/tls/registry.crt
        key: /etc/pki/tls/private/registry.key
auth:
    htpasswd:
        realm: centlinux.com
        path: /etc/docker-distribution/dockerpasswd

Warning: Avoid use of TAB key for indention of lines. Otherwise, the service will give you following error during startup.

configuration error: error parsing /etc/docker-distribution/registry/config.yml: yaml: line 12: found character that cannot start any token

Please refer to Docker Documentation for more configuration options in config.yml.

Start and Enable Secure Registry service.

systemctl start docker-distribution
systemctl enable docker-distribution

Allow Docker Registry service port 5000/tcp in Linux Firewall.

firewall-cmd --permanent --add-port=5000/tcp
firewall-cmd --reload

Use Secure Docker Registry in Docker Containers

Connect with Docker Host (docker-manager-01.centlinux.com) by using ssh as root user.

Add an entry in Local DNS Resolver to setup name resolution of our Secure Registry Server.

cat >> /etc/hosts << EOF
192.168.116.153 dregistry-01.centlinux.com dregistry-01
EOF

Install Registry Service TLS/SSL certificate on Docker Container.

mkdir -p /etc/docker/certs.d/dregistry-01.centlinux.com:5000
scp root@dregistry-01:/etc/pki/tls/registry.crt /etc/docker/certs.d/dregistry-01.centlinux.com:5000/

Pull an image from Docker Hub. We will later push this image into our Secure Docker Registry.

docker pull alpine

Output:

Using default tag: latest
latest: Pulling from library/alpine
8e402f1a9c57: Pull complete
Digest: sha256:644fcb1a676b5165371437feaa922943aaf7afcfa8bfee4472f6860aad1ef2a0
Status: Downloaded newer image for alpine:latest

Tag alpine image before pushing it to Secure Docker Registry.

docker tag alpine dregistry-01.centlinux.com:5000/alpine

Login to Secure Registry.

docker login dregistry-01.centlinux.com:5000

Output:

Username: ahmer
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 alpine image to our Secure Docker Registry.

docker push dregistry-01.centlinux.com:5000/alpine

Output:

The push refers to repository [dregistry-01.centlinux.com:5000/alpine]
bcf2f368fe23: Pushed
latest: digest: sha256:d05ecd4520cab5d9e5d877595fb0532aadcd6c90f4bbc837bc11679f704c4c82 size: 528

We have Successfully configured a Secure Registry with Docker-Distribution on CentOS 7.

Frequently Asked Questions (FAQs)

What is Docker-Distribution?
Docker-Distribution is an open-source tool that allows you to host your own Docker registry, enabling you to store and manage Docker images privately.

Why would I need a private Docker registry?
A private registry is useful for storing proprietary or custom Docker images securely within your organization, without exposing them to public repositories like Docker Hub.

What are the prerequisites for setting up Docker-Distribution on CentOS 7?
You need a CentOS 7 server with Docker installed, sufficient storage for images, and basic knowledge of Docker concepts like images and containers.

Is Docker-Distribution secure by default?
No, the basic setup runs over HTTP, which is insecure. For production, you should configure TLS/SSL encryption and authentication for secure access.

How do I push and pull images from my private registry?
After setup, you can push images using docker push and pull them with docker pull, specifying your registry’s address (e.g., myregistry.example.com/image-name).

The Ultimate Ubuntu Handbook: A complete guide to mastering Ubuntu 24.04—from installation to advanced security and development

$49.99 (as of June 21, 2025 20:12 GMT +00:00 – More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)

Final Thoughts

Setting up Docker-Distribution on CentOS 7 provides you with a private and secure registry to store and manage your container images. By completing the installation and configuration steps, you now have greater control over your image distribution process, enhancing both security and performance within your development and deployment workflows.

To maintain a reliable registry, ensure you implement proper access controls, enable SSL encryption, and regularly monitor and back up your data. With your private Docker registry in place, you are well-positioned to streamline container management across your organization.

Struggling with Linux server management? I offer professional support to ensure your servers are secure, optimized, and always available. Visit my Fiverr profile to learn more!

Thank you for reading, and good luck with your Docker-Distribution setup!