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.

Practice

1. What is the main purpose of using a registry mirror in Docker?

easy

A. To speed up image downloads by using a closer copy

B. To create new Docker images automatically

C. To secure Docker images with encryption

D. To delete unused Docker images from the local system

Solution

1. Step 1: Understand what a registry mirror does

   A registry mirror stores copies of Docker images closer to the user to reduce download time.

2. Step 2: Identify the main benefit

   This setup speeds up image downloads by avoiding long-distance network calls to the main registry.

3. Final Answer:

   To speed up image downloads by using a closer copy -> Option A

4. Quick Check:

   Registry mirror purpose = speed up downloads [OK]

Hint: Mirrors make image downloads faster by local caching [OK]

Common Mistakes:

• Thinking mirrors create images
• Confusing mirrors with security features
• Assuming mirrors delete images

2. Which of the following is the correct way to add a registry mirror in Docker's daemon configuration file daemon.json?

easy

A. { "registry-mirror": ["https://mirror.example.com"] }

B. { "registry": ["https://mirror.example.com"] }

C. { "mirrors": ["https://mirror.example.com"] }

D. { "registry-mirrors": ["https://mirror.example.com"] }

Solution

1. Step 1: Recall the correct key name for mirrors

   The Docker daemon.json uses the key "registry-mirrors" (plural) to list mirror URLs.

2. Step 2: Match the correct JSON syntax

   The value must be an array of strings with mirror URLs, correctly formatted as shown.

3. Final Answer:

   { "registry-mirrors": ["https://mirror.example.com"] } -> Option D

4. Quick Check:

   Key is "registry-mirrors" with array [OK]

Hint: Use plural "registry-mirrors" key with array in daemon.json [OK]

Common Mistakes:

• Using singular "registry-mirror" key
• Using wrong key like "mirrors" or "registry"
• Not using an array for URLs

3. Given the following daemon.json snippet, what will happen when Docker tries to pull an image?

{
  "registry-mirrors": ["https://mirror1.example.com", "https://mirror2.example.com"]
}

medium

A. Docker will try mirror1 first, then mirror2 if mirror1 fails

B. Docker will download from both mirrors simultaneously

C. Docker ignores mirrors and pulls from the default registry only

D. Docker will fail to pull because multiple mirrors are not allowed

Solution

1. Step 1: Understand mirror priority

   Docker tries mirrors in the order listed, using the first mirror available.

2. Step 2: Confirm behavior with multiple mirrors

   If the first mirror fails, Docker tries the next mirror in the list before falling back to the default registry.

3. Final Answer:

   Docker will try mirror1 first, then mirror2 if mirror1 fails -> Option A

4. Quick Check:

   Mirrors tried in order, fallback if needed [OK]

Hint: Docker tries mirrors in list order, stops at first success [OK]

Common Mistakes:

• Thinking Docker downloads from all mirrors at once
• Assuming mirrors are ignored
• Believing multiple mirrors cause errors

4. You added a registry mirror URL to daemon.json but Docker still pulls images from the default registry. What is the most likely cause?

medium

A. The mirror URL is listed as a string, not inside an array

B. The mirror URL is missing the https:// prefix

C. Docker daemon was not restarted after editing the file

D. Docker does not support registry mirrors

Solution

1. Step 1: Check Docker daemon reload requirement

   Changes to daemon.json require restarting the Docker daemon to take effect.

2. Step 2: Identify common mistake

   Not restarting Docker after editing daemon.json causes the old config to remain active.

3. Final Answer:

   Docker daemon was not restarted after editing the file -> Option C

4. Quick Check:

   Restart Docker after config changes [OK]

Hint: Always restart Docker after changing daemon.json [OK]

Common Mistakes:

• Forgetting to restart Docker daemon
• Ignoring correct JSON array format
• Assuming Docker lacks mirror support

5. You want to configure Docker to use a registry mirror at https://mirror.example.com and ensure it is used for all image pulls. Which steps should you follow?

hard

A. Set an environment variable DOCKER_MIRROR=https://mirror.example.com and restart Docker

B. Add the mirror URL to daemon.json under "registry-mirrors", then restart Docker daemon

C. Add the mirror URL to ~/.docker/config.json and run docker pull --mirror

D. Run docker mirror add https://mirror.example.com command

Solution

1. Step 1: Configure mirror in daemon.json

   Add the mirror URL inside the "registry-mirrors" array in Docker's daemon.json file.

2. Step 2: Restart Docker daemon

   Restart Docker to apply the new mirror configuration so it is used for all image pulls.

3. Final Answer:

   Add the mirror URL to daemon.json under "registry-mirrors", then restart Docker daemon -> Option B

4. Quick Check:

   daemon.json + restart = mirror active [OK]

Hint: Edit daemon.json and restart Docker to activate mirror [OK]

Common Mistakes:

• Trying to configure mirror in wrong file
• Using non-existent Docker commands
• Setting environment variables instead of config