How to Set Up a Private Registry Mirror

A Docker mirror can only accelerate images from docker.io, not images from private registries.

1. Why You Need a Private Registry Mirror

Rate limiting on the public network
Docker Hub pull rate limits
Reduce image pull time

2. Create a Registry Image Acceleration Service

Generate a configuration file

version: 0.1
log:
  fields:
    service: registry
storage:
  cache:
    blobdescriptor: inmemory
  filesystem:
    rootdirectory: /var/lib/registry
http:
  addr: :5000
  headers:
    X-Content-Type-Options: [nosniff]
health:
  storagedriver:
    enabled: true
    interval: 10s
    threshold: 3

But a service started this way can only act as a Registry, not a Mirror. A Registry stores images and serves them directly; a Mirror fetches image data from a Registry and forwards it to clients.

Add the proxy field to the config.yml file

Many features can be configured in config.yml, such as authentication keys and storage backends. Here we only add the proxy field; the final config.yml looks like this:

version: 0.1
log:
  fields:
    service: registry
storage:
  cache:
    blobdescriptor: inmemory
  filesystem:
    rootdirectory: /var/lib/registry
http:
  addr: :5000
  headers:
    X-Content-Type-Options: [nosniff]
health:
  storagedriver:
    enabled: true
    interval: 10s
    threshold: 3
proxy:
  remoteurl: https://registry-1.docker.io

If you use private images, you can fill in the account and password in the following format, but the remoteurl here does not support self-hosted private registries — it can only point at the official Docker registry. This is explained in the official documentation: https://docs.docker.com/registry/recipes/mirror/.

1
2
3
4
proxy:
  remoteurl: https://registry-1.docker.io
  username: [username]
  password: [password]

Start the mirror service

Create the storage directory

1
mkdir data

Start the service

docker run -d --security-opt apparmor=unconfined --security-opt seccomp=unconfined -p 5000:5000 --restart=always --name mirror \
             -v `pwd`/config.yml:/etc/docker/registry/config.yml \
             -v `pwd`/data:/var/lib/registry \
             registry:2

Check the service

1
2
3
4
docker ps

CONTAINER ID   IMAGE        COMMAND                  CREATED          STATUS          PORTS                    NAMES
fc10fdef7e3f   registry:2   "/entrypoint.sh /etc…"   1 minutes ago   Up 1 minutes   0.0.0.0:5000->5000/tcp   mirror

3. You Can Also Use Dragonfly’s Mirror Mode

Add a configuration file dfget.yaml

1
vim dfget.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
proxy:
  security:
    insecure: true
  tcpListen:
    listen: 0.0.0.0
    port: 5000
  registryMirror:
    dynamic: true
    url: https://index.docker.io
  proxies:
    - regx: blobs/sha256.*
keepStorage: true
storage:
  taskExpireTime: 6h
  diskGCThreshold: 50Gi

Add the storage directory

1
mkdir dfdata

Start the Dfdaemon service

1
2
3
4
docker run -d --security-opt apparmor=unconfined --security-opt seccomp=unconfined --name dragonfly-dfdaemon --restart=always --net=host \
        -v `pwd`/dfdata:/var/lib/dragonfly \
        -v `pwd`/dfget.yaml:/etc/dragonfly/dfget.yaml \
        dragonflyoss/dfdaemon:v2.0.4

There is no need to deploy any other Dragonfly services here, and the Dfdaemon component can perform lifecycle management on images, which is an advantage over a Registry.

4. Configure a Registry Mirror on the Docker Daemon

Modify Docker’s configuration file daemon.json

In the /etc/docker/daemon.json file, add the registry mirror

1
2
3
4
{
  "registry-mirrors": ["http://127.0.0.1:5000"],
  "live-restore": true
}

When live-restore is true, restarting Docker does not affect running containers.

Reload the configuration

1
2
systemctl daemon-reload
systemctl restart docker

Check the Docker configuration

1
docker info

Test pulling images

1
2
docker pull centos
docker pull ubuntu

Check the size of the cached data

1
2
3
du -sh data

157M	data

5. Summary

This post set up a docker.io mirror acceleration service using two approaches: Registry and Dragonfly.

Both approaches are simple and easy to maintain, and in an office network or an IDC network they can greatly accelerate docker.io image pulls and save on bandwidth costs.