Registry Mirrors and Pull-Through Caching in Docker
Configure registry-mirrors in daemon.json and deploy pull-through caching proxies to optimize bandwidth, eliminate Docker Hub rate limits, and accelerate container builds.
Published on • November 17, 2026
AI Assistant

In enterprise networks and CI/CD clusters, repeatedly pulling public base images like ubuntu, python, or node from Docker Hub causes significant external bandwidth consumption, introduces latency, and risks triggering Docker Hub HTTP 429 rate limits.
Configuring a pull-through cache and setting up registry-mirrors in Docker daemon configuration solves these challenges by transparently caching public container image layers within your local network.
How Registry Mirrors Work
When a Docker host executes docker pull alpine:latest with a configured registry mirror:
- The daemon first sends the pull request to the local pull-through cache proxy.
- If the image layers exist in the local proxy cache (cache hit), they are returned immediately over LAN speeds.
- If the image layers are missing (cache miss), the proxy fetches them from the upstream registry (e.g., Docker Hub), stores them locally, and streams them back to the daemon.
- If the mirror proxy is unreachable, the daemon automatically falls back to pulling directly from the public registry.
+-------------------+ 1. pull image +------------------------+
| Docker Host | ---------------------> | Local Registry Mirror |
| (dockerd) | | (Pull-Through Cache) |
+-------------------+ +------------------------+
| |
| 3. Fallback (if mirror down) | 2. Fetch on cache miss
v v
+---------------------------------------------------------------------+
| Public Docker Hub Registry |
+---------------------------------------------------------------------+
Setting Up a Local Pull-Through Cache
You can run an official Docker Distribution Registry instance configured in proxy cache mode using Docker Compose:
docker-compose.yml
version: '3.8'
services:
registry-cache:
image: registry:2
container_name: registry-cache
restart: always
ports:
- "5000:5000"
environment:
REGISTRY_PROXY_REMOTEURL: https://registry-1.docker.io
# Optional Docker Hub authentication credentials to avoid anonymous rate limits upstream
REGISTRY_PROXY_USERNAME: mydockerhubuser
REGISTRY_PROXY_PASSWORD: mydockerhubpassword
volumes:
- ./cache-data:/var/lib/registry
Start the cache server:
docker compose up -d
Configuring Docker Hosts to Use the Mirror
On every node in your cluster, update /etc/docker/daemon.json to include the registry-mirrors array pointing to your cache endpoint:
{
"registry-mirrors": [
"http://192.168.1.50:5000"
]
}
If your registry mirror uses HTTPS with a self-signed certificate, include it under insecure-registries or add its TLS CA certificate to /etc/docker/certs.d/:
{
"registry-mirrors": [
"https://cache.internal.domain:5000"
],
"insecure-registries": [
"cache.internal.domain:5000"
]
}
Reload daemon configuration without interrupting running workload containers:
sudo systemctl reload docker
Verifying Mirror Configuration
Run docker info and look for the Registry Mirrors section near the bottom of the output:
docker info
Sample verification output:
Registry Mirrors:
http://192.168.1.50:5000/
Live Restore Enabled: true
Now, pull a public image:
docker pull postgres:16-alpine
Check the logs of your registry-cache container to verify local interception and layer caching:
docker logs -f registry-cache
time="2026-11-17T12:05:00Z" level=info msg="response completed" go.version=go1.22.5 http.request.host="192.168.1.50:5000" http.request.method=GET http.request.uri="/v2/library/postgres/manifests/16-alpine" http.response.status=200
Benefits for Enterprise and CI/CD Pipelines
- Rate Limit Mitigation: Solves anonymous rate limit constraints (100 pulls / 6 hours per IP) across build clusters.
- Bandwidth & Speed: Image pulls download at local network line speeds (1Gbps/10Gbps), drastically reducing pipeline duration.
- Resilience: Even during public registry micro-outages, cached base image layers remain accessible locally.
Limitations: Standard OCI registry mirrors cache public repositories (like official Docker Hub images). Private registries typically require dedicated proxy configurations or repository-specific prefix mirrors.
Takeaway: registry-mirrors in /etc/docker/daemon.json seamlessly redirects image pulls to a local pull-through cache proxy. This setup protects CI pipelines against rate limits, accelerates container start times, and conserves external network bandwidth.