Set up Docker Registry Proxy Cache Server

17 / Dec / 2015 by Navjot Singh 1 comments

With the large scale adoption of the Docker by the developers, it becomes necessary to provide a proxy cache server for Docker registry where Docker image once downloaded from Docker Hub can be retrieved again from the local proxy server. This saves us a lot of time from downloading the image again and again from Docker Hub.


Set up a local proxy server for Docker registry which should cache all the images getting downloaded by the Docker users and should serve the already downloaded image from its cache if any other Docker user makes a new pull request.

We will use the official registry image version 2 (registry:2) provided by Docker to implement the scenario.

Before we start with the setup, please ensure the Docker engine version is of version 1.8.3 or later. Below steps can be followed to implement our scenario.

  1. Pull Docker image named registry:2:
    [js]docker pull registry:2 [/js]
  2. Create a directory (say /mnt/registry-cache) where the registry will save the cached images:
    [js]mkdir -p /mnt/registry-cache[/js]
  3. Configure the registry to make it work as registry proxy cache. We will be modifying configuration file present in registry image.
    Get the file from the image as follows:
    [js]docker run -it --rm --entrypoint cat registry:2 /etc/docker/registry/config.yml > /mnt/registry-cache/config.yml[/js]
  4. The content of the config.yml file is:
    [js]<br />version: 0.1<br />log:<br />  fields:<br />    service: registry<br />storage:<br />  cache:<br />    blobdescriptor: inmemory<br />  filesystem:<br />    rootdirectory: /var/lib/registry<br />http:<br />  addr: :5000<br />  headers:<br />    X-Content-Type-Options: [nosniff]<br />  health:<br />    storagedriver:<br />    enabled: true<br />    interval: 10s<br />    threshold: 3[/js]
  5. Add below section into the file to enable proxy caching:
    [js]<br />proxy:<br />  remoteurl:<br />  username: &lt;dockerhub username&gt;<br />  password: &lt;dockerhub password&gt;[/js]
  6. Fields “username” and “password” are optional. If provided, it will enable caching of the private images for the account associated with the provided username.
    Note: Provide username and password only if it is required and ensure the access to the registry proxy server is restricted.
  7. For a secure connection between the Docker Engines running of various developer’s machines and the registry proxy cache server, we will use a TLS certificate.
    In case, no TLS certificate is present, we can use the self-signed certificate as follows:
    [js]cd /mny/registry-cache<br />openssl req -x509 -nodes -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365<br />[/js]
  8. While using the self-signed certificate please ensure, that you share your “cert.pem” file created in above command to all the Docker users who will be using the registry proxy cache server. They need to update the certificates on their systems as follows on ubuntu 14.04:
    [js]cp cert.pem /usr/share/ca-certificates/<br />  [/js]
  9. Append the certificate name in “/etc/ca-certificates.conf” file:
    [js]echo “cert.pem” &gt;&gt; /etc/ca-certificates.conf[/js]
  10. Update the trusted certificates in “/etc/ssl/certs” directory by using the following command:
    [js]update-ca-certificates --fresh[/js]
  11. Modify the “http” section as below:
    [js]<br />http:<br />  addr: :5000<br />  headers:<br />    X-Content-Type-Options: [nosniff]<br />  tls:<br />    certificate: /var/lib/registry/cert.pem<br />    key: /var/lib/registry/key.pem[/js]
  12. The final config.yml file will be:
    [js]<br />version: 0.1<br />log:<br />  fields:<br />    service: registry<br />storage:<br />  cache:<br />    blobdescriptor: inmemory<br />  filesystem:<br />    rootdirectory: /var/lib/registry<br />http:<br />  addr: :5000<br />  headers:<br />    X-Content-Type-Options: [nosniff]<br />  tls:<br />    certificate: /var/lib/registry/cert.pem<br />    key: /var/lib/registry/key.pem<br />health:<br />  storagedriver:<br />    enabled: true<br />    interval: 10s<br />    threshold: 3<br />proxy:<br />  remoteurl:<br />  username: xxxxxxxxxx<br />  password: xxxxxxxxxx[/js]
  13. Start the registry proxy server as follows:
    [js]docker run -d --restart=always -p 5000:5000 --name v2-mirror -v /mnt/registry-cache:/var/lib/registry registry:2 /var/lib/registry/config.yml[/js]

    We have mapped /mnt/registry-cache directory to the container. Container uses the certificate and store the cache images in this directory.

  14. Verify if the registry is working fine by using below command:
    [js]<br />curl -I https://&lt;url of your registry server&gt;:5000/v2/[/js]
    [js]<br />HTTP/1.1 200 OK<br />Content-Length: 2<br />Content-Type: application/json; charset=utf-8<br />Docker-Distribution-Api-Version: registry/2.0<br />X-Content-Type-Options: nosniff<br />Date: Thu, 17 Dec 2015 01:39:17 GMT<br />[/js]
  15. Make sure the “URL” is same as we provided in while creating a self-signed certificate.
  16. Configure the Docker Engine on every Docker user’s system using this registry proxy cache server by running the below commands on their system:
    [js]echo 'DOCKER_OPTS="--registry-mirror=https://&lt;url of your registry server&gt;:5000" ' &gt;&gt; /etc/default/docker<br />service docker restart<br />      [/js]
  17. Now, from any Docker user’s system, make a pull of any image (say busybox as its size is very small):
    [js]docker pull busybox[/js]
  18. Check the cache of  registry  proxy server for busybox image as follows:
    [js]curl  https://&lt;url of your registry server&gt;:5000/v2/_catalog<br />  {"repositories":["library/busybox","library/ubuntu"]}[/js]
  19. If we got the above output, our registry proxy cache server is working fine.

Now, the images which have been already pulled would be saved on registry proxy server in directory “/mnt/registry-cache”. This will reduce the redundant pulls from the Docker Hub and save us a lot of time.

In case you need help for your Docker project, get in touch with our Docker DevOps experts


comments (1 “Set up Docker Registry Proxy Cache Server”)

  1. hanxirui

    I meet a problem,and below is the log. Can anybody help me? Thanks.
    server certificate verification failed. CAfile: /etc/ssl/certs/ca-certificates.crt CRLfile: none


Leave a Reply

Your email address will not be published. Required fields are marked *