How to Set Up Docker Registry Mirror for Faster Pulls

How to Set Up Docker Registry Mirror for Faster Pulls

A Docker registry mirror caches container images locally, dramatically reducing pull times and bandwidth usage. This is especially valuable when running multiple Breeze instances that pull the same images repeatedly.

Why Use a Registry Mirror

• Faster pulls — cached images are served locally instead of from remote registries
• Reduced bandwidth — each image is downloaded from the internet only once
• Reliability — continue pulling images even during upstream registry outages
• Rate limit avoidance — avoid hitting pull rate limits on public registries

Deploying a Registry Mirror with Docker

Run an official Docker registry in mirror mode on your Breeze server:

docker run -d --name registry-mirror \
  -p 5000:5000 \
  -v registry_mirror_data:/var/lib/registry \
  -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
  -e REGISTRY_STORAGE_DELETE_ENABLED=true \
  --restart unless-stopped \
  registry:2

Docker Compose Configuration

services:
  registry-mirror:
    image: registry:2
    ports:
      - "5000:5000"
    environment:
      REGISTRY_PROXY_REMOTEURL: https://registry-1.docker.io
      REGISTRY_STORAGE_DELETE_ENABLED: "true"
      REGISTRY_STORAGE_CACHE_BLOBDESCRIPTOR: inmemory
    volumes:
      - mirror_data:/var/lib/registry
    restart: unless-stopped

volumes:
  mirror_data:

Configuring Docker to Use the Mirror

Edit /etc/docker/daemon.json on each Breeze instance that should use the mirror:

{
  "registry-mirrors": ["http://mirror-breeze-ip:5000"],
  "insecure-registries": ["mirror-breeze-ip:5000"]
}

Restart Docker to apply the changes:

sudo systemctl restart docker

Verifying the Mirror Works

# Pull an image (first pull fetches from upstream, subsequent pulls use cache)
docker pull nginx:latest

# Check the mirror's catalog
curl -s http://mirror-breeze-ip:5000/v2/_catalog | jq .

# Verify cached repositories
curl -s http://mirror-breeze-ip:5000/v2/library/nginx/tags/list | jq .

Adding HTTPS for Production

For secure mirror access across your network, configure TLS:

services:
  registry-mirror:
    image: registry:2
    ports:
      - "443:5000"
    environment:
      REGISTRY_HTTP_TLS_CERTIFICATE: /certs/fullchain.pem
      REGISTRY_HTTP_TLS_KEY: /certs/privkey.pem
      REGISTRY_PROXY_REMOTEURL: https://registry-1.docker.io
    volumes:
      - mirror_data:/var/lib/registry
      - /etc/letsencrypt/live/mirror.yourdomain.com:/certs:ro

Storage Management

Cached images accumulate over time. Set up garbage collection to reclaim space:

# Run garbage collection
docker exec registry-mirror bin/registry garbage-collect /etc/docker/registry/config.yml

# Schedule with cron for weekly cleanup
0 2 * * 0 docker exec registry-mirror bin/registry garbage-collect /etc/docker/registry/config.yml

Best Practices

• Place the mirror on a Breeze instance with fast storage and good network connectivity
• Monitor disk usage and schedule regular garbage collection
• Use HTTPS in production environments for secure communication
• Consider separate mirrors for different upstream registries if needed