Docker Registry Mirror Configuration Guide

The Docker Registry Proxy acceleration service is designed for developers, DevOps engineers, and CI/CD pipelines to eliminate TLS handshake timeouts, connection resets, and throttled download speeds when pulling Docker Hub and international container images.

We support Docker Hub, GitHub Packages (GHCR), Google GCR, Kubernetes (registry.k8s.io / k8s.gcr.io), Red Hat Quay, Microsoft MCR, NVIDIA NGC, AWS ECR Public, and virtually all mainstream container registries.

1. Direct Command-Line Pulling (Recommended & Zero Configuration)

Without modifying any local daemon files, simply prepend the proxy domain directly before the image name:

# 1. Official Docker Hub Library Images
docker pull gh-proxy.org/docker/nginx:latest
docker pull gh-proxy.org/docker/ubuntu:22.04

# 2. Architectured Image Prefixes
docker pull gh-proxy.org/docker/amd64/nginx:latest

# 3. Third-party Docker Hub Organizations
docker pull gh-proxy.org/docker/cleverest/crproxy
docker pull gh-proxy.org/docker/adguard/adguardhome
docker pull gh-proxy.org/docker/docker.io/adguard/adguardhome

# 4. Google Container Registry (GCR)
docker pull gh-proxy.org/docker/gcr.io/kaniko-project/executor:debug

# 5. GitHub Container Registry (GHCR)
docker pull gh-proxy.org/docker/ghcr.io/openfaas/queue-worker

# 6. Kubernetes Registry (registry.k8s.io)
docker pull gh-proxy.org/docker/registry.k8s.io/kube-apiserver:v1.30.0

# 7. Legacy Kubernetes Registry (k8s.gcr.io)
docker pull gh-proxy.org/docker/k8s.gcr.io/etcd:3.5.7-0

# 8. Red Hat Quay (quay.io)
docker pull gh-proxy.org/docker/quay.io/calico/cni

# 9. Microsoft Container Registry (MCR)
docker pull gh-proxy.org/docker/mcr.microsoft.com/powershell

# 10. Elastic Container Registry
docker pull gh-proxy.org/docker/docker.elastic.co/elasticsearch/elasticsearch:8.1.0

# 11. NVIDIA GPU NGC Registry
docker pull gh-proxy.org/docker/nvcr.io/nvidia/cuda:12.1.0-runtime-ubuntu20.04

# 12. AWS ECR Public
docker pull gh-proxy.org/docker/public.ecr.aws/nginx/nginx:latest

# 13. GitLab Container Registry
docker pull gh-proxy.org/docker/registry.gitlab.com/gitlab-org/cli:v1.45.0

# 14. Red Hat Universal Base Images (UBI)
docker pull gh-proxy.org/docker/registry.access.redhat.com/ubi8/ubi:latest

# 15. Oracle Container Registry
docker pull gh-proxy.org/docker/container-registry.oracle.com/os/oraclelinux:8

# 16. SUSE / openSUSE Registries
docker pull gh-proxy.org/docker/registry.suse.com/suse/sle15:latest
docker pull gh-proxy.org/docker/registry.opensuse.org/opensuse/tumbleweed:latest

2. Docker Daemon vs Prefix Proxy Mechanism

[!IMPORTANT] Core Routing Architecture & Compatibility GH-Proxy uses URL Path Prefix Routing, resolving images under the path pattern gh-proxy.org/docker/<image-name>. The standard Docker client daemon.json specification for registry-mirrors only accepts hostnames without URL subpaths (e.g. https://gh-proxy.org). When pulling, Docker daemon strips custom subpaths and targets /v2/ directly at the root, which bypasses our intelligent multi-registry proxy router. Therefore, we strongly recommend using the prefix syntax in all production and development environments (e.g., direct CLI pulls, Dockerfile, Docker Compose, Kubernetes manifests, and Podman configurations). It is completely non-intrusive and works immediately.

If you are using container tooling that natively supports registry path rewrites (such as Podman), seamless registry remapping is fully supported (see the Podman section below).

3. Kubernetes (K8s) Deployment Configuration

In Kubernetes resource manifests (such as Deployment or Pod YAML files), specify the accelerated proxy path directly in the image field:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: gh-proxy.org/docker/ghcr.io/nginxinc/nginx-unprivileged:latest
          ports:
            - containerPort: 80
        - name: redis
          image: gh-proxy.org/docker/ghcr.io/bitnami/redis:alpine
          ports:
            - containerPort: 6379

4. Docker Compose Configuration

In your docker-compose.yml file, configure the image property of each service to use the accelerated mirror:

version: "3.8"
services:
  web:
    image: gh-proxy.org/docker/ghcr.io/nginxinc/nginx-unprivileged:latest
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html

  database:
    image: gh-proxy.org/docker/mcr.microsoft.com/mssql/server:2022-latest
    environment:
      ACCEPT_EULA: Y
      SA_PASSWORD: "MyStrongPassword123!"
    volumes:
      - mssql_data:/var/opt/mssql

  cache:
    image: gh-proxy.org/docker/ghcr.io/bitnami/redis:alpine
    ports:
      - "6379:6379"

volumes:
  mssql_data:

5. Multi-Stage Dockerfile Optimization

When writing Dockerfiles, replacing the FROM base image with the accelerated proxy dramatically reduces layer download times during builds:

# Builder stage using accelerated Node base image
FROM gh-proxy.org/docker/ghcr.io/nodejs/node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Production runtime stage
FROM gh-proxy.org/docker/ghcr.io/nginxinc/nginx-unprivileged:latest
COPY --from=builder /app/dist /usr/share/nginx/html

# Example: Microsoft .NET runtime acceleration
FROM gh-proxy.org/docker/mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
COPY --from=builder /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

6. CI/CD Pipeline Integration (GitHub Actions Example)

In GitHub Actions workflows or self-hosted GitLab CI runners, you can dynamically pass the accelerated base image using --build-arg:

name: Build and Deploy
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build with accelerated base images
        run: |
          docker build -t myapp:latest \
            --build-arg BASE_IMAGE=gh-proxy.org/docker/ghcr.io/nodejs/node:18-alpine .

      - name: Test with accelerated images
        run: |
          docker run --rm \
            gh-proxy.org/docker/mcr.microsoft.com/dotnet/runtime:8.0 \
            dotnet --version

7. Podman Registry Remapping

For environments running Podman instead of Docker, configure registry prefix rewrites in /etc/containers/registries.conf:

# Edit /etc/containers/registries.conf
[[registry]]
prefix = "ghcr.io"
location = "gh-proxy.org/docker/ghcr.io"

Or pull directly using the proxy path:

podman pull gh-proxy.org/docker/ghcr.io/alpine/alpine:latest
podman pull gh-proxy.org/docker/ghcr.io/nginxinc/nginx-unprivileged:latest

8. Containerd Runtime Configuration

For Kubernetes clusters using containerd as the Container Runtime Interface (CRI), configure mirror endpoints in /etc/containerd/config.toml:

# Edit /etc/containerd/config.toml
[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."ghcr.io"]
    endpoint = ["https://gh-proxy.org/docker/ghcr.io"]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
    endpoint = ["https://gh-proxy.org/docker/gcr.io"]

Then restart containerd to apply changes:

sudo systemctl restart containerd

[!TIP] Recommended Kubernetes Best Practice In production clusters, we recommend declaring the accelerated image path directly in the Deployment or Pod YAML (image: gh-proxy.org/docker/...). This avoids mutating host-level daemon configurations and guarantees identical behavior across worker nodes.

Important Notices

Free & Community Driven: This mirror service is strictly intended for accelerating legitimate open-source development and container deployment. Any malicious use or security penetration activity is strictly prohibited.
Public Images Support: The acceleration cluster serves public container repositories. For security and authentication isolation, private registries requiring login credentials are not proxied.
Broad Protocol Compatibility: Fully compatible with Docker CLI, Podman, Containerd, CRI-O, Kubernetes, and popular orchestration systems.
Anycast Edge Failover: Edge health checks monitor routing health continuously. In the event of network disruption, requests are failover-routed to healthy cluster nodes in milliseconds.