Docker Registry Mirror

The Docker registry is an essential functionality of the Docker ecosystem. The Docker registry is a central repository or hub that allows the users to store and share the Docker container images. Using the Docker registry, you can easily create, upload, and share your container images. You can then update and perform the changes to the images and automatically apply them to the image.

Docker images are the blueprints for creating containers. They contain all the necessary components and instructions to run a specific application or service.

Before using an image, you need to have it downloaded on the local machine; however, this can get very inefficient quickly. This is where the Docker registry comes into play. You can download the images that you want from any host with the Docker installed.

What Is the Docker Registry Mirror?

A Docker registry mirror refers to a specialized copy of the registry that can serve as a cache or proxy to quickly and efficiently manage the Docker images.

The primary purpose of a registry mirror is to improve the efficiency and speed of retrieving and distributing the images in a Docker environment.

When you need to use a Docker image, you must download it to your local machine. However, repeatedly downloading the images from the internet can become inefficient, especially when dealing with large images or in situations with limited bandwidth.

This is where the Docker registry mirror comes into play. Instead of fetching the images directly from the internet, you can configure your Docker environment to pull the images from a nearby Docker registry mirror.

A common use case is when you are running multiple instances of Docker. For example, if you are running a lab that uses Docker as its virtualization technology. Instead of each Docker daemon going to the internet and fetching the image when needed, you can set up a local registry mirror and allow all the Docker daemons to fetch the images from it, reducing the extra traffic.

How to Run the Docker Registry Mirror

The best way to run a Docker registry mirror is using the registry image provided by Docker. This image contains the Docker registry implementation which allows you to store and distribute the Docker images.

Start by running the “pull” command to download the image as shown in the following command:

$ docker pull registry


Once the image is downloaded, we must create a configuration file for the registry mirror. An example is as follows:

version: 0.1
    service: registry
    blobdescriptor: inmemory
  addr: :5000
    X-Content-Type-Options: [nosniff]
    enabled: true
    interval: 10s
    threshold: 3

You can save this file into any directory that you choose, provided that you have the read and write access.

Next, run the Docker registry mirror container, providing the path to the configuration file that we just created. We must also specify the port where we wish to expose the container.

$ docker run -d -p 5000:5000 --restart=always --name=registry-mirror -v /path/to/config.yml:/etc/docker/registry/config.yml registry:2

Depending on the version, you can skip the configuration and run with the default values using the command as follows:

$ docker run -d -p 5000:5000 --restart always --name registry registry:2


Configure the Docker Daemons

Once the mirror is running, you can configure the Docker daemons to use the registry mirror by editing the daemon configuration file. This is usually located in /etc/docker/daemon.json.

Add the mirror URL under the registry-mirrors key.

  "registry-mirrors": ["https://<my-docker-mirror-host>"]

Save the file and reload the Docker Engine for the change to take effect.

Test The Registry Mirror

You can test the mirror by pulling an image from Docker Hub. The mirror should cache the image locally, reducing the download time. For example:

$ docker pull alpine

The first pull is from Docker Hub, but subsequent pulls of the same image should be significantly faster.


In this tutorial, you learned how to configure a Docker registry mirror to speed up the download and distribution of the Docker images.

About the author

John Otieno

My name is John and am a fellow geek like you. I am passionate about all things computers from Hardware, Operating systems to Programming. My dream is to share my knowledge with the world and help out fellow geeks. Follow my content by subscribing to LinuxHint mailing list