How to Change Docker’s Package Source

[doggie]

This article was converted by SimpRead; original URL: wxhzhwxhzh.github.io

Asao VitePress Site

Table of Contents ​

• What Is a Docker Image Registry?
• Why Change the Registry?
• Commonly Used Domestic Registries
• How to Change the Registry
• Verifying the Configuration
• Troubleshooting Common Issues
• Practical Usage Examples

What Is a Docker Image Registry? ​

A Docker image registry (or registry mirror) is a service for storing and distributing Docker images. By default, Docker uses the official Docker Hub (registry-1.docker.io) as its image registry.

When you run docker pull redis, Docker actually downloads the image from registry-1.docker.io/library/redis.

Why Change the Registry? ​

Using the official Docker Hub registry in mainland China often results in the following issues:

1. Slow network speed: Extremely long download times for images
2. Connection timeouts: Frequent context deadline exceeded errors
3. Unstable connections: Downloads frequently interrupted, requiring repeated attempts

Therefore, using domestic registry accelerators can significantly improve the Docker user experience.

Commonly Used Domestic Registries ​

Provider	Registry URL	Description
Alibaba Cloud	https://xxxxxx.mirror.aliyuncs.com	Requires registration to obtain a personalized URL
Tencent Cloud	https://mirror.ccs.tencentyun.com	Public service
NetEase	https://hub-mirror.c.163.com	Public service
USTC (University of Science and Technology of China)	https://docker.mirrors.ustc.edu.cn	Public service
Qiniu Cloud	https://reg-mirror.qiniu.com	Public service
DaoCloud	https://f1361db2.m.daocloud.io	Public service

How to Change the Registry ​

Method 1: Configure Docker Registry Mirrors (Recommended) ​

This is the most common and recommended approach — configure once, and all docker pull commands will use the mirrors automatically.

Linux System Configuration ​

1. Create or edit the Docker configuration file

   bash

   sudo mkdir -p /etc/docker
   sudo nano /etc/docker/daemon.json
   

2. Add registry mirror configuration

   json

   {
     "registry-mirrors": [
       "https://hub-mirror.c.163.com",
       "https://docker.mirrors.ustc.edu.cn",
       "https://reg-mirror.qiniu.com"
     ]
   }
   

3. Restart the Docker service

   bash

   sudo systemctl daemon-reload
   sudo systemctl restart docker
   

Windows System Configuration ​

1. Right-click the Docker Desktop icon in the system tray

2. Select “Settings”

3. In the left menu, select “Docker Engine”

4. Add registry mirrors to the JSON configuration:

   json

   {
     "registry-mirrors": [
       "https://hub-mirror.c.163.com",
       "https://docker.mirrors.ustc.edu.cn"
     ]
   }
   

5. Click “Apply & Restart”

macOS System Configuration ​

1. Click the Docker Desktop icon in the menu bar
2. Select “Preferences”
3. Select “Docker Engine”
4. Add registry mirror configuration (same as Windows)
5. Click “Apply & Restart”

Method 2: Use Alibaba Cloud’s Personalized Registry Mirror ​

Alibaba Cloud provides personalized registry mirrors that are typically faster and more stable.

1. Register an Alibaba Cloud account at Alibaba Cloud Container Registry

2. Obtain your personalized mirror URL

   • After logging in, go to the Container Registry console
   • Click “Image Tools” → “Image Accelerator” on the left sidebar
   • Copy your personalized accelerator URL

3. Configure the mirror, following instructions provided on the page (typically editing /etc/docker/daemon.json):

   json

   {
     "registry-mirrors": ["https://xxxxxx.mirror.aliyuncs.com"]
   }
   

Method 3: Pull Directly from Domestic Registries ​

If you prefer not to modify global configurations, you can pull directly from domestic registries:

bash

# Pull from Alibaba Cloud
docker pull registry.cn-hangzhou.aliyuncs.com/library/redis:latest

# Pull from Tencent Cloud
docker pull ccr.ccs.tencentyun.com/library/redis:latest

# Retag to standard name
docker tag registry.cn-hangzhou.aliyuncs.com/library/redis:latest redis:latest

Verifying the Configuration ​

Check Registry Mirror Configuration ​

bash

# View Docker info to confirm registry mirror settings
docker info

# Search for the "Registry Mirrors" section
docker info | grep -A 10 "Registry Mirrors"

After successful configuration, output should resemble:

Registry Mirrors:
 https://hub-mirror.c.163.com/
 https://docker.mirrors.ustc.edu.cn/

Test Download Speed ​

bash

# Remove local image (if exists)
docker rmi redis:latest

# Test download speed
time docker pull redis:latest

Test Registry Connectivity ​

bash

# Test NetEase mirror
curl -I https://hub-mirror.c.163.com/v2/

# Test USTC mirror
curl -I https://docker.mirrors.ustc.edu.cn/v2/

# Expected normal response: HTTP/1.1 200 OK or HTTP/2 200

Troubleshooting Common Issues ​

Issue 1: DNS Resolution Failure ​

Error message:

Could not resolve host: mirror.ccs.tencentyun.com

Solution:

1. Verify network connectivity

2. Change DNS servers:

   bash

   # Temporarily change DNS
   echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
   echo "nameserver 114.114.114.114" | sudo tee -a /etc/resolv.conf
   

3. Try other available mirrors

Issue 2: Registry Unavailable ​

Error message:

Error response from daemon: Get https://xxx: dial tcp: lookup xxx on 127.0.0.53:53: no such host

Solution:

1. Test registry availability
2. Remove unavailable mirrors from the configuration
3. Configure multiple mirrors as fallback options

Issue 3: Insufficient Permissions ​

Error message:

Got permission denied while trying to connect to the Docker daemon socket

Solution:

bash

# Add current user to the docker group
sudo usermod -aG docker $USER

# Re-login, or execute:
newgrp docker

Issue 4: Invalid Configuration File Format ​

Error message:

unable to configure the Docker daemon with file /etc/docker/daemon.json

Solution:

1. Validate JSON syntax
2. Use an online JSON validator to check correctness
3. Ensure the file encoding is UTF-8

Practical Usage Examples ​

Example 1: Pulling Common Images ​

bash

# Pull different versions of images
docker pull redis:latest
docker pull redis:6.2
docker pull nginx:alpine
docker pull mysql:8.0
docker pull node:16

# List downloaded images
docker images

Example 2: Building a Dockerfile with Base Images ​

dockerfile

# Dockerfile
FROM node:16-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

EXPOSE 3000
CMD ["npm", "start"]

bash

# Build the image
docker build -t my-node-app .

Example 3: Using docker-compose ​

yaml

# docker-compose.yml
version: '3.8'

services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
  
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

bash

# Start services
docker-compose up -d

Best Practices ​

1. Use Multiple Mirrors: Configure several mirrors as fallbacks to improve reliability
2. Regular Testing: Periodically test mirror availability and download speeds
3. Prefer Stable Providers: Prioritize mirrors offered by reputable providers (e.g., Alibaba Cloud, Tencent Cloud)
4. Personalized Mirrors for Enterprises: For enterprise users, consider using personalized accelerators like those from Alibaba Cloud
5. Backup Configuration Files: Maintain backups of Docker configuration files to enable rapid deployment across environments

Summary ​

Configuring Docker registry mirrors significantly enhances the Docker experience in mainland China. We recommend configuring mirrors globally via the configuration file — this ensures all Docker operations benefit from acceleration after a single setup.

If issues arise, refer to the troubleshooting section of this guide for diagnosis and resolution. Keep in mind that performance of different mirrors may vary over time; maintaining flexible configurations is therefore essential.