Docker Registry Cache

What this article covers

• What a pull-through cache is.
• How to set up a local registry mirror.
• Configuration for Docker Engine and BuildKit.
• Benefits and limitations.
• Operational tips.

Introduction: Docker Registry Cache

If you regularly build Docker images or run many containers, you end up downloading the same images repeatedly. A registry cache, also called a pull-through cache or registry mirror, stores downloaded images locally and serves them on subsequent requests. This saves bandwidth, accelerates builds, and reduces dependency on external registries like Docker Hub.

This article shows you how to set up your own Docker registry cache.

Key terms

• Pull-through cache: A proxy that fetches and caches images on demand.
• Registry mirror: An alternative source for Docker Hub.
• Docker Distribution: Docker’s reference registry implementation.
• BuildKit: Docker’s modern builder.
• Image cache: Images stored locally.
• Proxy mode: Registry acts as a pass-through.
• Bandwidth: Network capacity used for transfers.
• Rate limit: Docker Hub restricts download frequency.

When a cache makes sense

• Many builds on the same machine.
• Multiple Docker hosts in a network.
• Slow or expensive internet connection.
• Avoiding Docker Hub rate limits.
• CI/CD pipelines with frequent builds.

Starting a simple registry cache

docker run -d -p 5000:5000 \
  --name registry-cache \
  -v /opt/registry-cache:/var/lib/registry \
  -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
  -e REGISTRY_PROXY_USERNAME=benutzer \
  -e REGISTRY_PROXY_PASSWORD=passwort \
  registry:2

This includes Docker Hub authentication to bypass rate limits.

Configuring Docker Engine

In /etc/docker/daemon.json:

{
  "registry-mirrors": ["http://localhost:5000"]
}

Then restart Docker:

sudo systemctl restart docker

BuildKit cache

BuildKit can use separate cache backends for layers. To cache images from a registry:

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB"
    }
  },
  "registry-mirrors": ["http://localhost:5000"]
}

In Compose

services:
  cache:
    image: registry:2
    ports:
      - "5000:5000"
    environment:
      REGISTRY_PROXY_REMOTEURL: https://registry-1.docker.io
      REGISTRY_PROXY_USERNAME: benutzer
      REGISTRY_PROXY_PASSWORD: passwort
    volumes:
      - registry-cache:/var/lib/registry

volumes:
  registry-cache:

Multiple hosts on the network

Other hosts can use the registry as a mirror:

{
  "registry-mirrors": ["http://cache-server:5000"]
}

Use HTTPS with your own certificate for added security.

Checking the cache

curl http://localhost:5000/v2/_catalog

Limiting cache size

Docker Registry has no built-in size limit. Clean it up periodically:

docker exec registry-cache bin/registry garbage-collect /etc/docker/registry/config.yml

Alternatively, set volume size limits.

Benefits

• Faster downloads.
• Reduced bandwidth usage.
• Independence from Docker Hub.
• Improved CI/CD times.
• Lower rate-limit exposure.

Limitations

• Only public images or those with supplied credentials.
• Not a replacement for a private registry.
• Caches layers, not build cache directly.
• Storage grows over time and requires maintenance.

Tips

• Enable TLS for external access.
• Clean up regularly.
• Store Docker Hub credentials.
• Monitor cache hit rates.
• Back up the volume.

Common pitfalls

• Cache not being used: registry-mirrors not set in daemon.json.
• Authentication fails: Incorrect Docker Hub credentials.
• Storage fills up: No cleanup routine in place.
• Missing HTTPS: Insecure communication.
• Stale cache: No invalidation strategy.
• Firewall: Port 5000 not open.

Further reading

• BotServ.de Docker Registry
• BotServ.de Docker Image Optimization
• BotServ.de Docker Layer Caching
• BotServ.de Docker Commands

FAQ: Docker Registry Cache

What’s the difference between a registry and a cache? A registry stores your own images. A pull-through cache fetches external images and stores them locally.

Can I replace Docker Hub entirely? No, but you can cache images and bypass rate limits.

Do I need Docker Hub authentication? Yes, for private images and higher limits.

Does this work with BuildKit? Yes, registry-mirrors applies during pulls.

Should I use TLS? Always, if the cache is accessible over the network.

Sources and further reading

• Docker Registry as pull-through cache: https://docs.docker.com/docker-hub/mirror/
• Docker Registry: https://distribution.github.io/distribution/
• BuildKit: https://docs.docker.com/build/buildkit/

Summary: Docker Registry Cache

A Docker registry cache cuts downloads, saves bandwidth, and speeds up builds. Set it up as a pull-through proxy and configure it as a registry-mirror in Docker Engine. For your own infrastructure or CI/CD pipeline, the payoff is quick. What matters most is proper authentication, TLS for external access, and regular maintenance to keep storage growth in check.