#Docker Mirror Configuration

Pulling images from Docker Hub can be slow depending on your location. Configuring registry mirrors can significantly improve download speeds. This chapter covers common mirror configuration methods.

#Why Use Registry Mirrors?

Docker Hub servers are located in specific regions. Users in other regions may experience:

• Very slow download speeds
• Connection timeouts
• Pull failures

Registry mirrors cache popular images on servers closer to your location, accelerating downloads.

#Common Registry Mirrors

⚠️ Mirror availability may change. Configure multiple mirrors as fallbacks.

#Linux Configuration

#Edit daemon.json

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": [
    "https://registry.docker-cn.com",
    "https://mirror.gcr.io"
  ]
}
EOF

#Restart Docker

sudo systemctl daemon-reload
sudo systemctl restart docker

#Verify Configuration

docker info | grep -A 5 "Registry Mirrors"

#Docker Desktop Configuration

#Windows / macOS

1. Open Docker Desktop
2. Go to Settings → Docker Engine
3. Add registry-mirrors to the JSON configuration:

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

4. Click "Apply & Restart"

#Test Mirror Speed

# Remove local image first
docker rmi nginx:latest

# Pull and measure time
time docker pull nginx:latest

#Alternative: Using a Proxy

If you have a proxy server, configure Docker to use it:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/proxy.conf <<EOF
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

#Self-Hosted Registry Mirror

For organizations, set up an internal registry mirror:

docker run -d \
  --name registry-mirror \
  --restart=always \
  -p 5000:5000 \
  -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
  registry:2

#Common Issues

#Mirror Not Working

# Verify config file format
cat /etc/docker/daemon.json | python3 -m json.tool

# Confirm Docker restarted
sudo systemctl restart docker

# Check Docker info
docker info

#Some Images Not Accelerated

Third-party registries (e.g., ghcr.io, quay.io) don't go through Docker Hub, so mirrors won't help. Use a proxy for those.

#Further Reading

• Docker Registry Mirror Documentation