Docker Registry Mirror: A Local Cache for Faster Pulls
A registry mirror is like a CDN for Docker images, caching public images on your local network to speed up pulls and avoid rate limits. Use it in CI/CD pipelines to reduce build times. The footgun: you can't `docker push` to a mirror; it's a.
WHY IT EXISTS: Pulling images from public registries like Docker Hub across the internet is slow and subject to rate limits. For a team or CI system pulling the same base images repeatedly, this creates a significant bottleneck and a single point of failure. A registry mirror solves this by caching images on the local network.
THE MENTAL MODEL: Think of a registry mirror as a Content Delivery Network (CDN) but for Docker images. Instead of every developer or CI runner going to the origin server (Docker Hub), they hit a local cache. This reduces external traffic and serves content from a much closer, faster source, just like a CDN does for websites.
HOW IT WORKS: You configure your Docker daemon with the mirror's URL. When you run a command like docker pull ubuntu:22.04, the daemon first sends the request to your mirror. If the mirror has a cached copy, it serves it immediately. If not, the mirror pulls the image from the upstream public registry, stores a copy for future requests, and then serves it to your daemon. This process is called a 'pull-through cache'.
WHEN TO USE IT: A mirror is ideal for CI/CD farms or large development teams where multiple hosts repeatedly pull the same public images. It drastically cuts down network latency for image pulls and helps you avoid hitting rate limits imposed by public registries, making your builds faster and more reliable.
WHEN NOT TO USE IT: A mirror is not a solution for hosting your own private images. It is a read-only cache for an upstream registry. For storing and distributing your own proprietary images, you need a full-fledged private registry like Harbor, Artifactory, or the open-source Docker Registry project. You cannot docker push to a mirror.
ONE CANONICAL EXAMPLE: A company's CI pipeline runs 100 builds an hour, each starting FROM node:18-alpine. Without a mirror, this triggers 100 separate downloads from Docker Hub, consuming bandwidth and risking rate-limiting errors. With a mirror, only the first build pulls from Docker Hub. The subsequent 99 builds fetch the image from the local mirror over the high-speed internal network, completing in seconds.
Read the original → docs.docker.com
Get five bites like this every day.
Tezvyn delivers a daily feed of 60-second tech bites with quizzes to lock in what you learn.