registry-mirror / pull-through cache

This host proxies and caches image pulls from registry-1.docker.io. Point your Docker daemon or containerd runtime here to speed up pulls and cut outbound rate-limit hits. Replace mirror.example.com below with this server's actual hostname.

01 — LINUX / DOCKER ENGINE

Edit daemon.json

Add this mirror as a registry-mirror in the Docker daemon config, then restart the daemon.

/etc/docker/daemon.json

{
  "registry-mirrors": ["https://mirror.example.com"]
}

shell

# apply the config
sudo systemctl daemon-reexec
sudo systemctl restart docker

If daemon.json already has other keys (e.g. log-driver, data-root), just add the registry-mirrors array — don't overwrite the file.

02 — DOCKER DESKTOP

macOS / Windows

Open Settings → Docker Engine, merge the same key into the JSON editor there, then click Apply & Restart.

Docker Desktop → Settings → Docker Engine

{
  "builder": { "gc": { "enabled": true } },
  "registry-mirrors": ["https://mirror.example.com"]
}

Same JSON, same panel. If you manage the daemon via WSL2 directly instead of Docker Desktop's GUI, edit /etc/docker/daemon.json inside the WSL distro as in step 01 and restart the docker service there.

03 — CONTAINERD / KUBERNETES

hosts.toml

For nodes running containerd (k3s, k8s, bare containerd) instead of the Docker daemon, configure a mirror per-registry:

/etc/containerd/certs.d/docker.io/hosts.toml

server = "https://registry-1.docker.io"

[host."https://mirror.example.com"]
  capabilities = ["pull", "resolve"]

Then restart containerd: sudo systemctl restart containerd

04 — VERIFY

Confirm the daemon picked it up

shell

docker info --format '{{ .RegistryConfig.Mirrors }}'

# pull something and check it came from the mirror
docker pull library/alpine
curl -s https://mirror.example.com/v2/ -o /dev/null -w "%{http_code}\n"

Check	Expected result
`docker info`	Mirror URL listed under `Registry Mirrors`
`GET /v2/`	`200` or `401` (both mean the mirror is reachable)
First pull of an image	Slower — cache miss, fetched from upstream and stored
Repeat pull of same image	Fast — served from local cache

05 — NOTES

Pull-through, not a full copy. A registry mirror only caches images as they're requested — it doesn't proactively sync the entire upstream registry. The first pull of any given image/tag is still fetched from docker.io.

Only pulls are mirrored — docker push still goes straight to Docker Hub or wherever the image is tagged for. If this mirror is served over plain HTTP internally, add it to insecure-registries instead of registry-mirrors, or terminate TLS in front of it.