Docker Registry Mirror Configuration#

On university networks, all students share a single public IP address. Docker Hub's pull rate limit (100 pulls / 6 h for unauthenticated requests) is exhausted almost immediately once a cohort starts a lab session. To work around this, the Artois University provides a local caching proxy at cache-ili.univ-artois.fr 1.

How to Configure the Mirror#

Edit /etc/docker/daemon.json and add:

{
  "registry-mirrors": ["http://cache-ili.univ-artois.fr:80/proxy_cache/"],
  "insecure-registries": ["cache-ili.univ-artois.fr:80"]
}

Then restart the daemon 2:

sudo systemctl restart docker

The full course walkthrough (steps 1–6) is in proxy.adoc.

⚠️ Known Issue: URL Path in registry-mirrors#

The registry-mirrors entry above contains a URL path component (/proxy_cache/). This is non-standard and functionally unverified.

Why Docker doesn't reject it: Docker's ValidateMirror function only checks that the scheme is http or https, that the URL has no query string, no fragment, and no embedded credentials. It does not reject paths. The normalized form is returned as strings.TrimSuffix(mirrorURL, "/") + "/" 3 — so Docker starts without error.

Why it may silently fail for implicit pulls: Docker's v2 Registry API expects the mirror to answer at the root path (/v2/…). When a mirror URL contains a path, the Docker client does not prepend that path to its API calls — it concatenates directly: http://cache-ili.univ-artois.fr:80/proxy_cache/v2/…. If the campus cache does not expose the v2 API under /proxy_cache/, implicit pulls silently fall back to Docker Hub — leaving the rate limit problem unsolved. This is tracked in Issue #443.

Recommended approach while unverified:

1. Explicit pull (always works): Specify the full cache path as part of the image reference 4:

   ⧉

   docker pull cache-ili.univ-artois.fr:80/proxy_cache/library/ubuntu:22.04
   

2. If implicit pulls don't work: Try dropping the path from registry-mirrors:

   ⧉

   {
     "registry-mirrors": ["http://cache-ili.univ-artois.fr:80"],
     "insecure-registries": ["cache-ili.univ-artois.fr:80"]
   }
   

   This matches Docker's documented mirror format (scheme + host only) 5. Then use the explicit pull syntax for the cache path.

Test on the campus network before the first session to confirm which form triggers transparent pull-through.

Additional Proxy Configuration#

For proxy settings needed inside Docker image builds (for package managers hitting the network during RUN), the course documents four options 6:

⚠️ The course currently labels the ENV approach "Recommended" (proxy.adoc L258), but this embeds credentials into the image layer (visible via docker history). Prefer the daemon-level or ~/.docker/config.json approach for credentials, or use BuildKit build secrets. Tracked in Issue #447.

Key References#