How Docker Hub caching works
Container images are made of a manifest, which a tag points to, and layers addressed by their digest. Tags move; digests never do. Cacheport re-checks tags every few minutes and keeps layers for as long as any cached manifest references them.
Official images live under library/ on Docker Hub. Through Cacheport, node:22-alpine becomes acme.cacheport.cc/hub/library/node:22-alpine. Image digests are identical, so pinned digests keep working.
- Manifests and tags
- Re-checked every 5 minutes, last good copy if Docker Hub is unreachable.
- Layers
- Cached by digest and shared between images.
- Multi-arch images
- Each platform's manifest and layers cached as they are pulled.
Set it up
Log in and pull
echo "$CACHEPORT_TOKEN" | docker login acme.cacheport.cc -u ci --password-stdin
docker pull acme.cacheport.cc/hub/library/node:22-alpineDockerfile with a switchable registry
ARG REGISTRY=acme.cacheport.cc/hub/
FROM ${REGISTRY}library/node:22-alpine
WORKDIR /app
COPY . .
RUN npm ci && npm run buildPassing --build-arg REGISTRY= with an empty value switches the Dockerfile back to Docker Hub, which is handy for contributors without a token. For other registries such as GHCR or Quay, see Container Mirror.
Use it in CI
Store the token as a secret named CACHEPORT_TOKEN, then pick your provider.
GitHub Actions
jobs:
image:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: docker/login-action@v3
with:
registry: acme.cacheport.cc
username: ci
password: ${{ secrets.CACHEPORT_TOKEN }}
- uses: docker/build-push-action@v6
with:
context: .
push: falseMore for GitHub Actions: GitHub Actions setup guide.
GitLab CI
test:
image: acme.cacheport.cc/hub/library/node:22-alpine
variables:
DOCKER_AUTH_CONFIG: $CACHEPORT_DOCKER_AUTH
script:
- npm ci
- npm testMore for GitLab CI: GitLab CI setup guide.
GitLab CI job images
GitLab runners pull job images before your script runs, so they need registry credentials up front. Store a Docker config JSON with an auths entry for acme.cacheport.cc in a masked CI/CD variable and expose it as DOCKER_AUTH_CONFIG, as in the example above.
Kubernetes and containerd
Clusters can use the same cache. With containerd, add a hosts.toml for docker.io that points at acme.cacheport.cc/hub so existing image references keep working, or rewrite image references in your manifests. Both approaches serve identical digests.
Troubleshooting
Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.