Formats and running it
A private Docker registry and Docker Hub mirror with scanning
Switch on container images and the box answers /v2/, so docker pull packages.example.com/library/nginx:1.25 comes through your rules, your cache and your scanners, and docker push works for the namespaces you reserve.
Add image registries the same way as npm and PyPI upstreams, with a name pattern deciding which repositories each one serves, so Docker Hub, GHCR, Quay and Harbor sit side by side. Docker Hub's token handshake is done for you, and a Docker Hub token avoids anonymous pull limits.
Everything is addressed by digest. A manifest is checked against the digest the registry claimed, a layer against the digest its manifest named, and nothing is stored until it matches. A tag is only a pointer: the digest it resolves to is recorded, and a tag that moves is logged and counted, so latest changing under you is visible rather than silent. A digest is only served when a tag the rules allow points at it, so a denied tag cannot be pulled by digest.
Rules decide repositories and tags, the kill switch refuses a repository or an exact digest, quarantine holds bytes back, and with image scanning on, each image is read layer by layer for operating system, npm and Python packages and checked against eight distributions' advisories.
Pushing your own images
Reserve a namespace like acme/* under Settings, Registries, Reserved names, then log in with a token whose owner is a publisher, approver or admin:
echo "$PUBLISH_TOKEN" | docker login packages.example.com -u ci-release --password-stdin
docker build -t packages.example.com/acme/storefront:1.4.0 .
docker push packages.example.com/acme/storefront:1.4.0Only reserved namespaces can be pushed, and a reserved name is never pulled from an upstream. Every blob is hashed on the way in and refused unless it is the digest docker named. A manifest may only name blobs this repository holds, at the sizes it says. Foreign layers that live elsewhere on the internet are refused, and blobs are never mounted from another repository. A blob on the kill switch is refused at the door.
Every pushed blob is held in quarantine until its malware scan is clean, so a pull of a fresh push gets toomanyrequests until then. A pushed tag never moves: pushing other content under it is refused, latest excepted. Nothing pushed is deleted. A good login gets a five minute bearer token that stops working the moment the ForgeRepo™ token behind it is revoked.
Honest limits: pushed images are kept for good, so plan the disk for them. An upload left untouched for an hour is swept, and a pushed blob no manifest names is removed a day later, but nothing a manifest names ever is. The reverse proxy in front needs room for large layers.
- Pick images to walk an image
In short
- docker, podman, skopeo, compose and Kubernetes
- Docker Hub, GHCR, Quay, Harbor and any v2 registry
- Digest checked manifests and layers, moving tags logged
docker pushto reserved namespaces, held until scanned clean- Pushed tags never move except
latest, nothing pushed is deleted - Layer by layer package inventory and advisories
In the documentation
- Sign docker in to packages.example.com Developer Guide
- Pull an image Developer Guide
- Push an image Developer Guide
- Build with a base image from packages.example.com Developer Guide
- Kubernetes and containerd Developer Guide
- Container images Administrator Guide
- Reserved names and publishing Administrator Guide
- Image scanning and "try again in a minute" Developer Guide
Goes well with
- Private npm registry npm, pnpm, Yarn and Bun. Publish your own packages under reserved names, mirror the rest.
- PyPI proxy and private index pip, uv and Poetry. PEP 503, 691, 658 and 700, and twine uploads for your own projects.
- Dependency confusion protection Reserve your npm scopes, PyPI prefixes, image namespaces and NuGet ids. A public package with your internal name is never fetched.
One container, about two minutes
A Linux box with Docker, or one without it, and a reverse proxy for TLS. The installer does the rest and it is safe to run twice. Free, MIT licensed, nothing to sign up for.