cacheport

Ecosystem · Containers

Docker Hub pull-through cache for CI

Every docker pull from a shared runner counts against Docker Hub's pull limits for that address. Pull through Cacheport instead: one authenticated client upstream, layers served from your region.

CP-DOCKERManifest
Upstream
Docker Hub (registry-1.docker.io)
Endpoint
acme.cacheport.cc/hub/
Example
acme.cacheport.cc/hub/library/node:22-alpine
Auth
docker login acme.cacheport.cc
Tags
Refreshed every 5 minutes
Layers
Cached by digest, immutable

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.

What gets cached
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

shell
echo "$CACHEPORT_TOKEN" | docker login acme.cacheport.cc -u ci --password-stdin
docker pull acme.cacheport.cc/hub/library/node:22-alpine

Dockerfile with a switchable registry

Dockerfile
ARG REGISTRY=acme.cacheport.cc/hub/
FROM ${REGISTRY}library/node:22-alpine
WORKDIR /app
COPY . .
RUN npm ci && npm run build

Passing --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

.github/workflows/ci.yml
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: false

More for GitHub Actions: GitHub Actions setup guide.

GitLab CI

.gitlab-ci.yml
test:
  image: acme.cacheport.cc/hub/library/node:22-alpine
  variables:
    DOCKER_AUTH_CONFIG: $CACHEPORT_DOCKER_AUTH
  script:
    - npm ci
    - npm test

More 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.

Questions

Does this get around Docker Hub's terms?

No. Cacheport pulls with an authenticated account and caches what it pulls, which is how Docker documents pull-through caches. Your use of the images is still governed by their licences.

Can I push images to Cacheport?

No. Push to your own registry; Cacheport caches pulls.

Do digests change?

No. Manifests and layers are served byte-identical, so image@sha256 references match.

Other ecosystems people set up next

Start on the free plan

20 GB of cache, every registry, unlimited users. Upgrade when your pipelines outgrow it.