Matt Bentley

How to Set Up a Registry Proxy Cache with Docker Open Source Registry

Matt Bentley

One of the latest beta features of the open source Docker v2 Registry is the ability to act as a registry proxy cache for images hosted at Docker Hub. Running a registry cache allows you to store images locally, reducing redundant image pulls across the Internet from Docker Hub. This capability is helpful for users with a large amount of Docker Engines in their environment. Instead of having each Engine pull from the Docker Hub all the time, by following this tutorial you can allow these Engines to pull from the local registry proxy cache to save time and bandwidth.

Here’s how you can get started:


Docker Engine 1.8.3
Docker Registry v2
Disk space to store Docker images
TLS certificate and key

Persistent data

In this example, we will assume that you are storing all of our persistent data on your local filesystem in the directory /data. This will include TLS certificate and key, configuration file, and cached images. We will mount this into the registry container later using a volume.

Securing your registry proxy cache

A registry proxy cache needs a TLS certificate to secure connections between the engines and registry hosting the cache. In this example, we will place our certificate (domain.crt) and key (domain.key) on our host in the /data directory. For additional information on securing a registry using TLS, see the Docker Registry 2.0 documentation.

Create a v2 registry proxy cache configuration

Next you will need to create a configuration file for the registry to act as a registry proxy cache. You can retrieve the default registry configuration file from the registry:2 image by using cat and a file redirection to create the configuration file:

$ docker run -it --rm --entrypoint cat registry:2 \
/etc/docker/registry/config.yml > /data/config.yml

I highly suggest retrieving the default configuration from the Docker image instead of using my example configuration as updates to the default configuration may occur over time.

Example default config.yml:

version: 0.1
      service: registry
         layerinfo: inmemory
         rootdirectory: /var/lib/registry
   addr: :5000

Update the ‘http’ section to configure TLS:

      addr: :5000
            certificate: /var/lib/registry/domain.crt
            key: /var/lib/registry/domain.key

Add a ‘proxy’ section to your configuration file to enable the cache

Click here for the documentation
      username: [username]
      password: [password]


The ‘username’ and ‘password’ settings are optional. Providing a Docker Hub username and password will allow the registry proxy cache to store any private images hosted on Docker Hub that are accessible from that account. Any images accessible by that user will be accessible through your image cache.

Be sure to fully understand the implications of providing Docker Hub credentials and ensure your mirror is secure and access is restricted! If you are unsure, do not include a username and password and your registry proxy cache will only cache public images.

Start your registry proxy cache container

$ docker run -d --restart=always -p 5000:5000 --name v2-mirror \
-v /data:/var/lib/registry registry:2 /var/lib/registry/config.yml


The above command utilizes a volume to mount /data from our host into the container allowing for persistent storage of cached images, TLS certificate and key, and customized registry configuration.

Verify your registry proxy cache is up and running

$ curl -I
HTTP/1.1 200 OK
Content-Length: 2
Content-Type: application/json; charset=utf-8
Docker-Distribution-Api-Version: registry/2.0
Date: Thu, 17 Sep 2015 21:42:02 GMT

Configure your Docker Engines to use the registry proxy cache

Update your Docker daemon arguments to include the --registry-mirror option:



For example, if your host is named and is running on port 5000, you would add the following option to the daemon arguments:



Refer to Configuring and running Docker on various distributions for more info on how to add daemon arguments.

Test your registry proxy cache

Pull an image from Docker Hub you currently do not have stored locally. For example, the busybox:latest image:

$ docker pull busybox:latest


Check the catalog to verify that the busybox image has been cached:

$ curl


You can also verify that the latest tag has been cached:

$ curl


Images will now be saved to your registry proxy cache as you pull them. Subsequent image pulls of images that have identical image manifests will be faster and the cache will maintain itself, purging images as they are no longer utilized.

For more information, check out the documentation.

Download Docker Engine and try to set up a Registry Proxy Cache with Docker Open Source Registry!


Watch this video from DockerCon 2015 with Stephen Day to learn more about Docker Registry

Slides from Stephen’s talk


 Learn More about Docker

• New to Docker? Try our 10 min online tutorial
• Sign up for a free 30 day trial of Docker
• Share images, automate builds, and more with a free Docker Hub account
• Read the Docker 1.8 Release Notes
• Subscribe to Docker Weekly
• Register for upcoming Docker Online Meetups
• Attend upcoming Docker Meetups
• Register for DockerCon Europe 2015
• Start contributing to Docker



8 thoughts on “How to Set Up a Registry Proxy Cache with Docker Open Source Registry

  1. If you want to cache pulls, but still want to push to Docker Hub, is there a way to use this? (I get a big “UNSUPPORTED” on pushes.)

  2. Hi,
    I have tried the steps but with docker 1.9 version.
    The images are not getting cached when I checked with curl command.

    Is it compatible with docker v1.9?

  3. Hi,
    Thanks for the blog.

    Using certificates is optional, right?
    I have tried it without certificates, it seems to be working fine for me.


  4. Robson Peixoto

    The the TLS really required ?
    My servers will access the mirror only in a private network.

  5. How do you configure the mirror registry if it is running behind a firewall?

  6. I am proxying a company internal Docker registry running API V2.0 using the config from your blog entry, and I can see the request being proxied by tailing the proxying docker registry logs.

    The proxy is requesting http.request.uri="/v2/library/my-image/manifests/latest" from the upstream, but I get an error: level=error msg="response completed with error" err.code="manifest unknown" err.detail="unknown tag=latest". The URL is is requesting is http.request.uri="/v2/library/my-image/manifests/latest", which does not seem to be a valid URL if I request it directly from the origin.

    However, the image does exist and I can pull it directly from the upstream. Is this some kind of API version incompatibility, do you think? Have you seen it before?

Leave a Reply