Methods for Accelerating Docker Image Pulls in China

Overview

Pulling Docker images in China can be painful — slow speeds, frequent disconnections, and rate limiting without an account 😣. Here are several methods to speed things up.

To summarize, you may encounter the following situations:

1. Slow download speeds / frequent disconnections in China: caused by network restrictions.
2. Rate limiting without a public registry account: major registries like Docker Hub have started rate-limiting anonymous (unauthenticated) users in recent years, throttling pull speeds and capping the number of image pulls within a given time window.

To address these issues, here are several approaches:

For slow download speeds / frequent disconnections in China, the available methods are:

1. Configure Docker Registry Mirrors that are accessible and reasonably fast within China
2. Self-host a Docker Registry Mirror/Proxy and configure it as a mirror
3. Configure proxies in the Docker Daemon

For rate limiting without a public registry account, the available method is:

1. Register accounts on each registry and log in with docker login

Details for each approach follow.

Detailed Approaches

│ 📝Notes:
│
│ Docker is used as the example here.
│ For Containerd/Podman/cri-o, apply the same concepts accordingly.

1. Configure Docker Registry Mirrors that are accessible and reasonably fast within China
   1. Alibaba Cloud Docker acceleration: a personal acceleration address like xxxxxx.mirror.aliyuncs.com
   2. DockerProxy acceleration: dockerproxy.com
   3. Baidu Cloud Mirror: mirror.baidubce.com
   4. …
2. Self-host a Docker Registry Mirror/Proxy and configure it as a mirror
   1. Here we use a Cloudflare Worker — cloudflare-docker-proxy
3. Configure Docker Daemon proxies, specifically: http-proxy https-proxy no-proxy
4. Register accounts on each registry and log in with docker login

Implementation Details

Configure Available Docker Registry Mirrors in China

Available Docker Registry Mirrors in China change over time, so you need to adjust your configuration based on current availability.

As of 2023/9/5, the available mirrors are:

1. Alibaba Cloud Docker acceleration: a personal acceleration address like xxxxxx.mirror.aliyuncs.com
2. DockerProxy acceleration: dockerproxy.com
3. Baidu Cloud Mirror: mirror.baidubce.com
4. DaoCloud: docker.m.daocloud.io
5. Nanjing University: docker.nju.edu.cn
6. Shanghai Jiao Tong University: docker.mirrors.sjtug.sjtu.edu.cn

Testing Docker Registry Mirror Availability in China

You can verify availability yourself. The manual method is to pull an image — here’s an example testing dockerproxy.com:

docker pull dockerproxy.com/library/nginx

A successful pull from within China confirms the mirror is working.

You can also check the GitHub repository: docker-practice/docker-registry-cn-mirror-test for GitHub Action results. For example, a recent run showed:

Applying for Alibaba Cloud Docker Acceleration

Alibaba Cloud Accelerator (click Management Console → log in → Image Tools on the right → Image Accelerator → copy the accelerator address)

Screenshot:

Other Acceleration Domains

1. DockerProxy acceleration: dockerproxy.com
2. Baidu Cloud Mirror: mirror.baidubce.com
3. Daocloud: docker.m.daocloud.io
4. Nanjing University: docker.nju.edu.cn
5. Shanghai Jiao Tong University: docker.mirrors.sjtug.sjtu.edu.cn

These are all fixed domains — just add them to your configuration directly.

Docker Acceleration Domains That Are No Longer Available

The following Docker acceleration domains are no longer available or are restricted to the corresponding cloud provider’s internal network:

• 163: hub-mirror.c.163.com
• USTC: docker.mirrors.ustc.edu.cn
• Tencent Cloud: mirror.ccs.tencentyun.com
• Azure China: dockerhub.azk8s.cn
• Qiniu Cloud: reg-mirror.qiniu.com
• Docker CN: registry.docker-cn.com

Docker Registry Mirror Configuration

Create or modify /etc/docker/daemon.json:

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-EOF
{
    "registry-mirrors": [
        "https://<changme>.mirror.aliyuncs.com",
        "https://dockerproxy.com",
        "https://mirror.baidubce.com",
        "https://docker.m.daocloud.io",
        "https://docker.nju.edu.cn",
        "https://docker.mirrors.sjtug.sjtu.edu.cn"
    ]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

Self-Hosting a Docker Registry Mirror/Proxy

Prerequisites

• A Cloudflare account
• (Optional) A custom domain hosted on Cloudflare
• Sufficient Cloudflare Workers quota

cloudflare-docker-proxy

Here we use a Cloudflare Worker — cloudflare-docker-proxy. The original README has some issues; you can refer to this README.md for implementation.

Here’s an example using a custom domain configuration:

1. Fork the repo
2. Update the Deploy button URL to point to your own repo URL
3. Modify the const routes block in src/index.js

const routes = {
  "docker.your-domain.com": "https://registry-1.docker.io",
  "quay.your-domain.com": "https://quay.io",
  "gcr.your-domain.com": "https://k8s.gcr.io",
  "k8s-gcr.your-domain.com": "https://k8s.gcr.io",
  "ghcr.your-domain.com": "https://ghcr.io",
};

4. Click the “Deploy” button to deploy. After deployment it looks like this:
   
5. Add a CNAME record in Cloudflare DNS pointing to the deployed ${workername}.${username}.workers.dev address. Example:
   
6. In Workers HTTP Routes, add xxx.your-domain.com/* routes pointing to cloudflare-docker-proxy, where xxx is docker, quay, gcr, etc. Example:
   

Done.

Docker Registry Mirror Configuration

Add your configured docker..com mirror to the registry-mirrors array in /etc/docker/daemon.json and restart Docker for the changes to take effect.

Configuring Docker Daemon proxies

If you prefer not to set up mirrors, you can configure proxies instead to pull Docker Hub images through a proxy.

Prerequisites

• A proxy that can reliably reach Docker Hub

Docker Daemon Configuration

vi /etc/docker/daemon.json, add the following:

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-EOF
{
    "proxies": {
        "http-proxy": "http://<proxy-ip>:7890",
        "https-proxy": "http://<proxy-ip>:7890",
        "no-proxy": "*.cn,127.0.0.0/8,192.168.0.0/16,172.16.0.0/12,10.0.0.0/8"
    }
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

│ 📝Notes:
│
│ The no-proxy field in Docker Daemon supports CIDR notation.

Done.

Register Accounts on Each Registry and Log In

Including but not limited to:

• Docker Hub
• Quay.io
• GHCR.io (GitHub’s Docker registry)
• gcr.io (Google Cloud’s Registry)
• …

After registration, depending on the registry, you may log in directly with a password, or you may need to create a Token/Service Account with a dedicated credential.

Registration steps are omitted here.

Log In with docker login

Docker Hub login:

echo "<password>" | docker login --username <username> --password-stdin'

Other Docker Registry logins:

echo "<password>" | docker login quay.io --username <username> --password-stdin
echo "<password>" | docker login ghcr.io --username <username> --password-stdin
echo "<password>" | docker login gcr.io --username <username> --password-stdin

Alternatively, you can write directly to the ~/.docker/config.json file:

{
  "auths": {
    "ghcr.io": {
      "auth": "<auth>"
    },
    "https://index.docker.io/v1/": {
      "auth": "<auth>"
    },
    "quay.io": {
      "auth": "<auth>"
    }
  }
}

is obtained as follows:

echo -n '<username>:<password>' | base64

Done.

Summary

With the methods above, you should be well-equipped to work with Docker smoothly in China.