Overview of Docker Registry

Reading Time: 4 minutes

The Docker Registry is open-source, under the permissive Apache license. Docker Registry is a storage where you can store and distribute the docker images. 

And why we need Docker Registry explained in below :

So let’s say you’re working on your project and you have your own docker images so you want to host your docker images locally for your office work , your organization, your team then you need to host your own docker registry.

So docker registry is a place where people can post their image and then other people can download it and we can tightly control where your images are being stored.

Similarly the same image might have multiple different versions.

Now we’ll take a look at setting up and configuring a local instance of the Distribution project where your teams can share images with docker commands they already know.For instance, by using:

 docker push and docker pull.


To work with docker registry, you will need the following:

  • Free Docker Account 
  • Docker running locally
  • The Registry is compatible with Docker engine version 1.6.0 or higher.

How to use Your own  Registry:

Now we can use registry by below methods:

  • Running the Distribution Service
  • Creating your own registry with docker compose

Running the Distribution service:

The Distribution project has been packaged as an Official Image on Docker Hub. To run a version locally, execute the following command:

$ docker run -d -p 5000:5000 –name registry registry:latest

The -d flag will run the container in detached mode After that -p flag publishes port 5000 on your local machine’s network. We also give our container a name using the –name flag. 

Creating your own registry:

Now we are aware of the registry  overview  and how they are used. Let’s continue by creating a private registry using docker-compose.

And we can have benefits using private registry similarly

You can control where your images can be stored and how you can access them by using Setting up Authentication.

version: ‘3’



    image: registry:2


    – “5000:5000”

Now save the file named as “docker-compose.yml”.

The configuration uses the official registry image with tag 2 after that, Default port of the registry image is 5000. Registry forwards the port 5000 of the container to the host machine. Therefore it allows us to send requests to port 5000 on the server that runs the registry.

You can now run the container using the following command:

$ docker-compose up -d

Now the container is running, we can continue with pushing/pulling an image to the registry.

Pushing and Pulling from a local registry

To check the running registry locally 

$ docker ps

Now let’s tail the container’s logs to verify that our image is being pushed and pulled locally:

$ docker logs -f registry

Open another terminal to  grab the node latest official image from Docker Hub. 

$ docker pull node

To push to or pull from our local registry, we need to add the registry’s location to the repository name. local.registry.address:port/repositoryname.

Now  we have to replace local.registry.address.port with localhost:5000  because our registry is running on our localhost and is listening on port 5000. 

So The full repository name: localhost:500/ubuntu. To do it,  run the docker tag command:

$ docker tag node localhost:5000/node

Now  push it to our local registry.

$ docker push localhost:5000/node

Pulling an image from the registry  can be done using a single command.

$ docker pull localhost:5000/node

You’ll see the message that the image already exists after that, you can remove the image and pull it again if you want to make sure that it functions correctly.

After that, you can run the image as follows.

$ docker run -it localhost:5000/node bash

Note: Most registries will require you to log in before pulling and pushing images for authentication purposes. To achieve this,

We can use some kind of basic authentication tool like htpasswd, which stores a secret file that helps you authenticate.

Create the authentication file:

To create we need to  install the htpasswd package:

htpasswd is used to create and update the flat-files used to store usernames and passwords for basic authentication of HTTP users.

 sudo apt install apache2-utils

Next, we will create a directory that will hold the password files.

mkdir auth

After that, we will continue by creating a user and file named as user1 and registry.password using the following command:

htpasswd -Bc registry.password user1

After executing the command, you will be prompted to enter your password.

NOTE: you can have multiple users with different password files.

Updating the docker-compose file:

Now that we have created the user1 using htpasswd, it is time to edit our docker-compose.yaml file.

version: ‘3’



    image: registry:2


    – “5000:5000”


      REGISTRY_AUTH: htpasswd


      REGISTRY_AUTH_HTPASSWD_PATH: /auth/registry.password


      – ./auth:/auth

For REGISTRY_AUTH you have to provide the authentication scheme you are using. similarly REGISTRY_AUTH_HTPASSWD_PATH is the path of the authentication file we just created above.

You can now restart your Docker set up to make the changes accessible.

$ docker-compose up –force-recreate

Log in to the registry:

Now that the registry is running with basic authentication, you can log in  by entering username and password.

$ docker login localhost:5000

Now  enter your username and password. after that successfully logging into your registry, you can push and pull images the same way as we did above.

To list the pushed images from private registry:

curl -X GET -u <uname>:<pass> http://localhost:5000/v2/_catalog

NOTE: You can view the username in registry.password file , either logging as root user or after changing the permission but  not the  password because it will store in an encrypted form.


I hope that this article helped you understand the basics of a container registry and how you can create your own and use it.

Written by 

A curious DevOps Intern , love to learn and working on technical skills/tools, know the basics of Linux, Docker, Ansible , Kubernetes and more..