Skip to content
Blog

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:

  1. The daemon first sends the pull request to the local pull-through cache proxy.
  2. If the image layers exist in the local proxy cache (cache hit), they are returned immediately over LAN speeds.
  3. 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.
  4. 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

  1. Rate Limit Mitigation: Solves anonymous rate limit constraints (100 pulls / 6 hours per IP) across build clusters.
  2. Bandwidth & Speed: Image pulls download at local network line speeds (1Gbps/10Gbps), drastically reducing pipeline duration.
  3. 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.

Sources