Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsRun Docker’s official Registry with a proxy configuration pointing to Docker Hub, then configure Docker Engine clients to use the registry as a mirror. The first request for an image is fetched upstream and cached; later requests can be served from local storage. This setup is for caching Docker Hub pulls—not for pushing images or mirroring multiple upstream registries.
How a pull-through cache works
A pull-through cache sits between Docker Engine and an upstream registry. On a cache miss, it retrieves the requested image from the upstream and stores it locally. Later pulls can use that cached content. Docker describes the Registry as configurable for pull-through caching in its Docker Hub mirror documentation.
For the standard Docker Engine mirror configuration described here, the upstream is Docker Hub. The cache proxies one upstream at a time, and Docker Engine’s registry-mirrors setting is for Docker Hub rather than arbitrary registries. If you need broader upstream coverage or additional policy features, consider a registry product or managed service instead.
What you need before setup
- A host that can run the official Registry image, with persistent disk for cached layers.
- A DNS name and TLS configuration appropriate for your environment. Protect the mirror with client authentication and network restrictions.
- Docker Engine clients that can reach the mirror over the configured URL.
- If you plan to use Docker Hub credentials, a least-privilege account. Credentials can expose every private repository visible to that account through the mirror.
Configure the Registry as a Docker Hub cache
The official Registry configuration requires a proxy section with remoteurl set to Docker Hub’s registry endpoint. CNCF Distribution recommends filesystem storage for cache performance and correctness. The following example enables deletion for later cleanup; uncomment and replace the credential values only if authenticated upstream access is required.
#1 Best Overall
version: 0.1
log:
fields:
service: registry
storage:
filesystem:
rootdirectory: /var/lib/registry
delete:
enabled: true
proxy:
remoteurl: https://registry-1.docker.io
# username: DOCKERHUB_USER
# password: DOCKERHUB_PASSWORD
# ttl: 168hSave this as /etc/docker/registry/config.yml, or use the configuration path appropriate to your deployment. Mount the configuration and /var/lib/registry as persistent storage when running the official Registry image. Docker identifies that image as the easiest deployment route in its mirror setup guide. The CNCF Distribution configuration reference documents the proxy options and filesystem storage.
If you configure a Docker Hub username and password, treat the mirror as a gateway to the private repositories visible to that account. Use TLS, authenticate clients, restrict network access, and avoid an account with broader access than the cache needs.
Point Docker Engine clients at the mirror
On each Docker Engine host, add the mirror URL to /etc/docker/daemon.json:
{
"registry-mirrors": ["https://mirror.example.com"]
}Replace the example with your mirror’s actual root-domain URL. Docker requires the mirror URL to be at the root of a domain; do not add a path component (an optional trailing slash is allowed). Restart or reload Docker Engine as required by the host so it reads the updated daemon configuration. The alternative daemon flag is --registry-mirror. See Docker’s configuration instructions for the relevant Engine setup.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
Test that the cache is working
- From a configured Docker Engine client, run
docker pull hello-world. - On the first request, expect the Registry to retrieve the image from Docker Hub and store it locally. An informational message that it is serving content from upstream is normal on a cache miss.
- Pull the same image again. The Registry can serve previously cached content locally, provided it remains in the cache and is still valid under the configured freshness behavior.
A successful pull confirms the client can reach the mirror and that the mirror can retrieve the requested image. It does not establish a particular bandwidth saving or pull-speed improvement; those depend on your workload and environment.
Manage storage and cache freshness
Control cache growth
Image churn can leave stale content on disk. Deletion must be enabled in the Registry configuration for cleanup. Schedule cleanup appropriate to your storage capacity and operational needs; when removed content is requested again, the cache fetches and stores it again from upstream. See the Docker mirror documentation and Distribution configuration reference.
Set a freshness window
Tag pulls check the remote for current content. To bound cache freshness, configure proxy.ttl. CNCF Distribution documents a default TTL of 168h (7 days); setting it to 0 disables expiration. The default is documented in the Distribution configuration reference. For example, uncomment ttl: 168h in the configuration to make that setting explicit.
Understand concurrent pulls
A single cache suppresses duplicate concurrent upstream pulls. A cluster of cache instances does not guarantee the same behavior: each instance maintains independent cache state, so simultaneous requests reaching different instances may each fetch upstream. The behavior is described in Docker’s mirror documentation.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteBest Value
- Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
- Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
Know the limitations before relying on the mirror
- Pull-only: pushing to a Registry configured as a pull-through cache is unsupported. Keep a separate writable registry for images built internally; see the Distribution documentation.
- One upstream: a cache proxies one upstream at a time. A standard Docker Engine registry mirror is intended for Docker Hub, not as a universal mirror setting for other registries. For broader upstream or policy needs, evaluate another product.
- Credentials affect exposure: configuring upstream credentials may make all private repositories visible to that Docker Hub account available through the mirror. Restrict access and use least privilege.
- No guaranteed savings figure: caching can reduce repeated upstream transfers, but the sources do not establish a fixed performance, bandwidth-saving, or rate-limit reduction percentage.
When to choose Harbor or Amazon ECR instead
Choose the simplest option that fits your upstream coverage, access controls, storage practices, freshness requirements, and operational capacity. These alternatives have different deployment and platform trade-offs; compare their current capabilities for your environment.
Quick Recap
| Option | Upstream coverage and pull model | Controls and operations to weigh | Platform and cost considerations |
|---|---|---|---|
| Official Distribution pull-through cache | One upstream per cache; standard Docker Engine mirror configuration supports Docker Hub. | Configure the proxy, client access, filesystem storage, cleanup, and TTL. Pushing is unsupported. | You operate the Registry host, storage, TLS, and upgrades. |
| Harbor proxy cache | Harbor documents projects that proxy an upstream registry and retain local copies for later requests; see Harbor proxy cache documentation. | Compare policy controls, vulnerability scanning, authentication integration, storage and garbage-collection behavior, and operational overhead. | Deployment and operating burden depend on how Harbor is hosted; cost is not stated in the cited documentation. |
| Amazon ECR pull-through cache | AWS documents pull-through cache rules and a namespaced image-pull syntax for Docker Hub content; see Amazon ECR pull-through cache documentation. | Review rule behavior, IAM access, quotas, freshness, and storage lifecycle for the account and region you will use. | Consider AWS region availability, cloud coupling, and applicable service costs; exact costs are not stated in the cited documentation. |
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
