Docker / OCI
Entrepot implements the OCI Distribution Spec (v2) with Docker token authentication. Because Docker clients address registries at the host root, the first path segment is the Entrepot repository and the rest is the image name:
docker pull entrepot.example.com/docker-hub/library/alpine:3.20 └────── host ──────┘ └─ repo ─┘ └─── image ──┘| Kind | Behaviour |
|---|---|
| hosted | docker push target. Chunked and monolithic uploads, cross-repository blob mounts, multi-platform manifest lists and OCI image indexes. Tags can move by default. |
| proxy | A pull-through cache of one registry: Docker Hub, ghcr.io, quay.io, registry.gitlab.com, public.ecr.aws, … Content is verified against its digest before caching. Tags are revalidated with cheap HEAD requests, which don’t count as Docker Hub pulls. |
| group | Tries members in order — e.g. your hosted images first, then the Docker Hub proxy. |
Create the repositories
Section titled “Create the repositories”api -X POST $E/api/v1/repositories -d '{"name":"docker-hub","format":"docker","kind":"proxy","blobStore":"s3","proxy":{"remoteUrl":"https://registry-1.docker.io"}}'api -X POST $E/api/v1/repositories -d '{"name":"ghcr","format":"docker","kind":"proxy","blobStore":"s3","proxy":{"remoteUrl":"https://ghcr.io"}}'api -X POST $E/api/v1/repositories -d '{"name":"docker-internal","format":"docker","kind":"hosted","blobStore":"s3"}'api -X POST $E/api/v1/repositories -d '{"name":"docker","format":"docker","kind":"group","blobStore":"s3","group":{"members":["docker-internal","docker-hub"]}}'proxy.remoteUrl must be the registry root (https://ghcr.io), without a
path. docker.io, index.docker.io and hub.docker.com are all mapped to
https://registry-1.docker.io.
Large registries are a good fit for an S3 blob store
with redirectDownloads, so layers are served straight from S3.
Log in, pull and push
Section titled “Log in, pull and push”echo "$ENTREPOT_TOKEN" | docker login entrepot.example.com -u token --password-stdin
# pull through the Docker Hub proxy (library/ is implied for official images)docker pull entrepot.example.com/docker-hub/library/alpine:3.20docker pull entrepot.example.com/docker-hub/alpine:3.20
# push to the hosted repositorydocker tag my-app:1.0 entrepot.example.com/docker-internal/team/my-app:1.0docker push entrepot.example.com/docker-internal/team/my-app:1.0podman login entrepot.example.com -u token -p "$ENTREPOT_TOKEN"podman pull entrepot.example.com/docker-hub/library/alpine:3.20podman push entrepot.example.com/docker-internal/team/my-app:1.0crane auth login entrepot.example.com -u token -p "$ENTREPOT_TOKEN"crane ls entrepot.example.com/docker-internal/team/my-appcrane copy alpine:3.20 entrepot.example.com/docker-internal/base/alpine:3.20
skopeo copy --dest-creds "token:$ENTREPOT_TOKEN" \ docker://alpine:3.20 docker://entrepot.example.com/docker-internal/base/alpine:3.20helm registry login entrepot.example.com -u token -p "$ENTREPOT_TOKEN"helm push mychart-0.1.0.tgz oci://entrepot.example.com/docker-internal/chartshelm install my-release oci://entrepot.example.com/docker-internal/charts/mychart --version 0.1.0OCI charts live in Docker repositories. For classic index.yaml
repositories see Helm.
Any username works; the password is the token. Anonymous pulls from
repositories with anonymousRead: true need no login.
Use Entrepot as a mirror
Section titled “Use Entrepot as a mirror”containerd (Kubernetes nodes)
Section titled “containerd (Kubernetes nodes)”To make a cluster pull Docker Hub images through Entrepot without changing
image references, configure a registry mirror in
/etc/containerd/certs.d/docker.io/hosts.toml:
server = "https://registry-1.docker.io"
[host."https://entrepot.example.com/v2/docker-hub"] capabilities = ["pull", "resolve"] override_path = trueoverride_path is needed because the repository name is part of the path.
containerd falls back to server if Entrepot is unreachable. Make sure
config_path = "/etc/containerd/certs.d" is set in containerd’s CRI
registry configuration.
Podman and CRI-O
Section titled “Podman and CRI-O”[[registry]]prefix = "docker.io"location = "docker.io"
[[registry.mirror]]location = "entrepot.example.com/docker-hub"Kubernetes image pull secrets
Section titled “Kubernetes image pull secrets”For private repositories, create a pull secret with a read-only service-account token:
kubectl create secret docker-registry entrepot \ --docker-server=entrepot.example.com \ --docker-username=token \ --docker-password="$ENTREPOT_TOKEN"From GitLab CI
Section titled “From GitLab CI”build-image: image: docker:27 services: [docker:27-dind] id_tokens: ENTREPOT_ID_TOKEN: aud: https://entrepot.example.com script: - echo "$ENTREPOT_ID_TOKEN" | docker login entrepot.example.com -u gitlab-ci --password-stdin - docker build -t entrepot.example.com/docker-internal/$CI_PROJECT_NAME:$CI_COMMIT_SHORT_SHA . - docker push entrepot.example.com/docker-internal/$CI_PROJECT_NAME:$CI_COMMIT_SHORT_SHATags, deletes and cleanup
Section titled “Tags, deletes and cleanup”- Hosted Docker repositories allow moving tags by default. Set
"hosted": {"allowRedeploy": false}for immutable tags. DELETE /v2/<repo>/<image>/manifests/<digest>deletes a manifest and its tags; deleting by tag removes just the tag.- A cleanup policy with
untaggedOlderThanDaysremoves untagged manifests and the layer links no remaining manifest references. Freed blobs are garbage-collected afterwards.
Troubleshooting
Section titled “Troubleshooting”http: server gave HTTP response to HTTPS client— for a plain-HTTP test setup, add the host to Docker’sinsecure-registries.unauthorized: authentication required—docker loginfirst, or enableanonymousReadon the repository.denied/403on a tag pull — the image may be quarantined. Tag and digest manifests are blocked in quarantine mode; layers never are.toomanyrequests— Docker Hub’s limit on the proxy’s upstream account; configureproxy.username/password.- Pushes fail behind an ingress — layer uploads need a large body size
and long timeouts. The Helm chart sets the nginx annotations
(
proxy-body-size: "0",proxy-request-buffering: "off", 900s timeouts); see Kubernetes. - Pulled the wrong image name — remember the first path segment is the
Entrepot repository:
entrepot.example.com/<repo>/<image>.