quay-mirror / pull-through cache

This host proxies and caches image pulls from quay.io. Point Docker or containerd here to speed up pulls of Red Hat, OpenShift, and community images and cut outbound rate-limit hits. Replace mirror.example.com below with this server's actual hostname.

01 — LINUX / DOCKER ENGINE

Edit daemon.json

Add this mirror as a registry-mirror in the Docker daemon config, then restart the daemon.

/etc/docker/daemon.json

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

shell

# apply the config
sudo systemctl daemon-reexec
sudo systemctl restart docker

Since Quay images are always pulled with the full quay.io/... reference, registry-mirrors alone may not intercept them on every client — the containerd hosts.toml approach below is the more reliable per-registry mirror.

02 — DOCKER DESKTOP

macOS / Windows

Open Settings → Docker Engine, merge the same key into the JSON editor there, then click Apply & Restart.

Docker Desktop → Settings → Docker Engine

{
  "builder": { "gc": { "enabled": true } },
  "registry-mirrors": ["https://mirror.example.com"]
}

03 — CONTAINERD / OPENSHIFT

hosts.toml, scoped to quay.io

For containerd nodes — including OpenShift / CRI-O — configure a mirror specifically for the Quay registry namespace:

/etc/containerd/certs.d/quay.io/hosts.toml

server = "https://quay.io"

[host."https://mirror.example.com"]
  capabilities = ["pull", "resolve"]

On OpenShift, the equivalent is an ImageContentSourcePolicy / ImageDigestMirrorSet applied cluster-wide rather than a per-node file edit:

ImageDigestMirrorSet

apiVersion: config.openshift.io/v1
kind: ImageDigestMirrorSet
metadata:
  name: quay-mirror
spec:
  imageDigestMirrors:
    - source: quay.io
      mirrors:
        - mirror.example.com

04 — VERIFY

Confirm the daemon picked it up

shell

docker info --format '{{ .RegistryConfig.Mirrors }}'

# pull a Quay image and check it came from the mirror
docker pull quay.io/prometheus/prometheus:latest
curl -s https://mirror.example.com/v2/ -o /dev/null -w "%{http_code}\n"

Check	Expected result
`docker info`	Mirror URL listed under `Registry Mirrors`
`GET /v2/`	`200` or `401` — mirror is reachable
First pull of an image	Slower — cache miss, fetched from upstream and stored
Repeat pull of same image	Fast — served from local cache

05 — NOTES

Pull-through, not a full copy. This mirror caches images as they're requested — it doesn't proactively sync the entire Quay catalog. The first pull of any given image/tag is still fetched from quay.io.

docker push still goes straight to Quay — this mirror only accelerates pulls. Quay repositories can be public or private; pulls from private repos still require your existing docker login quay.io credentials even when routed through the mirror. If this mirror is served over plain HTTP internally, add it to insecure-registries instead of registry-mirrors, or terminate TLS in front of it.