Docker private registry with Authentication| Standalone

Dylan Hunt
Apr 20, 2019 · 4 min read


Docker registry - It is a server that stores the Docker images for distribution. One can pull the images from registry to local or can push the locally build images to server for reuse in different servers or for different teams. We can simply compare the Docker registry with GitHub in its usage. Here we’re pushing the code along with its dependency in a Docker image format.

You should use the Registry if you want to:

  • tightly control where your images are being stored
  • fully own your images distribution pipeline
  • integrate image storage and distribution tightly into your in-house development workflow

Why ?

Security - If you’re going to build it for a public use or if it is one of your side project it is OK to use the default Docker Hub for storing your images. Which by default is visible to everyone in the internet. But what if it is one of your organizations project? or it is having a code which shouldn't be accessed by anyone other than few authorized people. Well you cannot keep more than one image in private if you’re using free Docker Hub account.

While we have 100’s of servers already running behind our applications it is wise to use one of them for our need here to store and retrieve the images instantly.

Running registries in a container mode is a de-facto instructions you’ll get if you search for it. But I often wonder why people going over that procedure while they can do a standalone one much easier and efficient than that. You need to go over lots of hustles to make a perfect registry in a container mode say for example to persist its volume to disc or to have authentication enabled or to up and running 24x7 even after a unknown server restart etc.


We are going to install a package called docker-distribution in our server which acts as a private registry for us in a server. It is also one of the official method from Docker itself.

For Debian and Ubuntu distributions

apt-get install -y docker-distribution

For RHEL and CentOS

yum install -y docker-distribution

After the installation of package the configuration and commands are pretty much same for all the distributions

We need to create a directory where the images will be stored securely. Lets say we’ll create a directory under root (/) directory as sources and another one as registry within it.

mkdir - p /sources/registry

Lets create a password file with list of users we need. We can add users in the same file in future also if needed. We need htpasswd utility to create a encrypted passwords using known hashes. If it is not preset in your server it can be downloaded by below command.

yum install -y httpd-tools

Lets create a directory to store the password file within our registry directory.

mkdir -p /sources/registry/auth

To create a encrypted password with bcrypt encryption which is highly secured and recommended one among all other hashing use the below command. We need to provide the directory location with file name where encrypted password will be stored. Here the last parameter is a username which is user defined one. Let’s call it as a admin user and enter the password when it prompts.

htpasswd -B -c /sources/registry/auth/passwdfile admin

Once the password is generated we can view it using any text editor/viewer

cat /sources/registry/auth/passwdfile

Which looks something similar to the below one


Lets edit the docker-distribution configuration file to make use of our password file and custom directories for storing the Docker images

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

Then change the filesystem location and add the authentication configurations like below.

version: 0.1
service: registry
layerinfo: inmemory
rootdirectory: /sources/registry
enabled: false
realm: basic-realm
path: /sources/registry/auth/passwdfile

Once we changed the configs and saved the file execute the below command to start the docker-distribution service.

systemctl enable docker-distribution
systemctl start docker-distribution
systemctl status docker-distribution

The above config file will start the service in default port which 5000 in our case. We can verify the service by browsing the below api

http://Public-IP or domain:5000/v2/_catalog

If everything is successfully configured you will be prompted to enter the username and password which is admin:admin in our case and able to see the list of repositories in JSON format

All our images pushing towards the registry will be stored in the /sources/registry directory which is also holds the auth file inside it. So making a periodic backup of the registry is also convenient here.

Happy sailing… adiós…


Dylan Hunt

Written by


Beovolytics integrates software assembly lines into large organizations by deploying solutions offered by the Cloud ecosystem.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade