Registry mirroring concept in Docker - Commands & Configuration

Introduction

Sometimes the official Docker registry is slow or unreachable. Registry mirroring helps by creating a local copy of images to speed up downloads and reduce internet use.

When your team is in a location with slow internet and pulling images from Docker Hub is slow.

When you want to reduce bandwidth costs by caching images locally.

When you want to ensure image availability even if Docker Hub is temporarily down.

When you manage many servers that use the same images and want faster startup times.

When you want to control which images are available internally for security reasons.

Config File - daemon.json

daemon.json

{
  "registry-mirrors": ["https://mirror.gcr.io"]
}

This file configures the Docker daemon to use a mirror registry.

registry-mirrors: List of URLs for mirror registries Docker will try first when pulling images.

Commands

Restart the Docker service to apply the new mirror configuration.

Terminal

sudo systemctl restart docker

Expected Output

No output (command runs silently)

Check Docker's current registry settings to confirm the mirror is active.

Terminal

docker info | grep Registry

Expected Output

Registry Mirrors:

 https://mirror.gcr.io

Pull an image to test if Docker uses the mirror registry for faster download.

Terminal

docker pull busybox

Expected Output

Using default tag: latest

latest: Pulling from library/busybox

Digest: sha256:3b1d5a7d3a2a5e3a8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8f8

Status: Downloaded newer image for busybox:latest

docker.io/library/busybox:latest

Key Concept

If you remember nothing else from this pattern, remember: registry mirroring speeds up image downloads by using a local or closer copy of Docker images.

Common Mistakes

Not restarting the Docker service after changing the daemon.json file.

Docker won't apply the new mirror settings until it restarts, so the mirror won't be used.

Always restart Docker with 'sudo systemctl restart docker' after editing daemon.json.

Using an invalid or unreachable mirror URL in the configuration.

Docker will fail to pull images or fall back to the default registry, causing delays or errors.

Use a valid, reachable mirror URL and test connectivity before configuring.

Summary

Configure Docker daemon with a registry mirror URL in daemon.json.

Restart Docker to apply the mirror settings.

Verify the mirror is active using 'docker info'.

Pull images to benefit from faster downloads via the mirror.