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

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:

Requirements

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:

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

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.

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.

Christoph

Mick Sear

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?