Distribution Registry
Stateless server that stores and serves container images and other OCI content, run as one container with filesystem or object storage and optional TLS and basic authentication.
| ID | distribution-registry |
| Layer | registry |
| Version | v3.1.2 |
| Tiers | T1 |
| Requires | nothing |
| License | Apache-2.0 |
| Evidence | docs |
| Last verified | 2026-11-22 |
Choose it when
Section titled “Choose it when”- A small internal image store is enough: the index page says to use the registry to tightly control where images are stored and to own the image distribution pipeline, and describes it as a stateless server application; the About page lists native TLS and basic authentication, webhook notifications, and storage drivers for the local filesystem, S3, Azure and Google Cloud Storage.
Avoid it when
Section titled “Avoid it when”- A web portal, projects with access roles and built-in vulnerability scanning are wanted: the pages read describe none of them for the registry (searched the About, index, deployment and configuration pages), and the harbor entry documents a portal and a Trivy-based scanner.
Caveats
Section titled “Caveats”- Docker (or another container engine) on the host is outside the catalog; the deployment page says a registry runs within Docker and that Docker must be installed on the host first.
- Harbor bundles a registry built from the distribution v2 line (the Makefile of Harbor v2.16.0 names the registry source version v2.8.3-patch-redis), while this entry is the v3 release line; the catalog does not compare them.
- No GPU documentation: searched docs/content and the README at the tag for gpu and nvidia on 2026-11-21 and found nothing; a registry stores images and does not run models.
- No paid edition or license check was found: the index page says the registry is open source under the Apache license.
Alternatives
Section titled “Alternatives”Carrying it in
Section titled “Carrying it in”| Image | Hardware | Digest |
|---|---|---|
registry:3.1.2 |
any | not pinned |
Downloads at run time
Section titled “Downloads at run time”What the software tries to fetch while it runs, and how to stage it instead.
- Images stored in the registry: the registry holds only what is pushed to it. The deployment page’s air-gap section says to build the registry’s data volume on a connected host that can docker pull the images wanted and then migrate the data volume to the air-gapped network; images with non-distributable layers (its example is the official Microsoft Windows base images) do not carry those layers into a private registry unless the Docker daemon is configured with allow-nondistributable-artifacts for it.
- Pull-through cache (only when configured): with the proxy section set (remoteurl, for example https://registry-1.docker.io), the registry fetches images from that upstream registry the first time they are requested and, for a tag pull, checks the remote for newer content; the mirror page says one upstream can be mirrored at a time and that Docker Hub mirrors remain subject to Docker’s fair usage policy. Leave proxy unset in an air-gapped site.
License server
Section titled “License server”No license server is contacted.
Telemetry and outbound calls
Section titled “Telemetry and outbound calls”| What | How to turn it off |
|---|---|
| OpenTelemetry trace export: the documentation says the registry uses OpenTelemetry for logs and traces, configured with the standard OTEL environment variables, and by default attempts to export traces to an OTLP collector on localhost:4318 (the deployment page: localhost:4318; the configuration page: https://localhost:4318/v1/traces). The target is the local host, so nothing leaves the host unless an OTEL variable points elsewhere. | OTEL_TRACES_EXPORTER=none (for example docker run -e OTEL_TRACES_EXPORTER=none …), documented on the deployment and configuration pages; the configuration page also allows setting it to a trace collector. |
Offline behavior is documented but not verified: the entry author did not run the registry, and the only air-gap documentation is the section named Considerations for air-gapped registries on the deployment page. The documented installation is a container started with docker run (docker run -d -p 5000:5000 –restart=always –name registry registry:3); the host needs Docker (the deployment page’s first sentence). The documentation says the default configuration is meant for development (log level debug, trace export on; see telemetry) and that a production registry must be protected by TLS and should ideally use access control. The image is a multi-platform manifest list: Docker Hub lists linux/amd64, linux/arm/v6, linux/arm/v7, linux/arm64/v8, linux/ppc64le, linux/riscv64 and linux/s390x for registry:3.1.2, so the platform of the target hosts has to be copied; there is no per-architecture file name to list. Alternative install route, not a carry item and not described by the installation pages read (BUILDING.md only mentions building an image from registry:3): the release v3.1.2 publishes binary archives registry_3.1.2_linux_amd64.tar.gz (x86_64), registry_3.1.2_linux_arm64.tar.gz, registry_3.1.2_linux_armv6.tar.gz, registry_3.1.2_linux_armv7.tar.gz, registry_3.1.2_linux_ppc64le.tar.gz, registry_3.1.2_linux_riscv64.tar.gz and registry_3.1.2_linux_s390x.tar.gz, each with a .sha256 file and a .provenance.json file; the documentation read does not describe installing from them. Documented settings: configuration file at /etc/distribution/config.yml in the image (the Docker Hub page mounts a custom file there), environment variables for single settings, storage by default on the local filesystem at /var/lib/registry, the debug address :5001 with Prometheus metrics at /metrics in the development configuration. Outbound calls: the only documented default is the trace export in telemetry, whose target is localhost; the pull-through cache above is off unless configured. No other telemetry, analytics, usage statistics, phone-home or update-check documentation was found on 2026-11-21 (searched docs/content, the README, BUILDING.md and the development configuration at the tag; a search is not proof of absence); vet before adoption. Two documentation pages differ slightly: the deployment page says traces are exported by default to an OTLP collector at localhost:4318, and the configuration page says traces are set to https://localhost:4318/v1/traces by default; this entry records both.
Evidence
Section titled “Evidence”All values were read on 2026-11-21 from the pages in sources (the Harbor Makefile named in the caveats was read on 2026-11-22, when the latest release v3.1.2 was checked again); the documentation is in the repository, cited at the release tag v3.1.2. The version v3.1.2 is the latest GitHub release (published 2026-09-24, not a prerelease). The documentation names the image as registry:3 (the moving tag of the 3 line) on its deployment and index pages and as distribution/distribution:edge on the Docker Hub page of the repository (docs/dockerhub.md); neither carries the exact version. The image row is registry:3.1.2: the tag exists on Docker Hub in the library/registry repository and, on 2026-11-21, had the same digest as registry:3 (sha256:82f6ff4a7f982960c8aa51617fea3aabc485df6e55cce80d22deb1de36f1bc3c), so it is the exact version of the documented image. The two documented names are not resolved further: edge is a rolling tag of a different repository and was not examined. The registry was not run by the entry author: the offline behavior is documented but not verified in a disconnected network.
Sources:
- https://api.github.com/repos/distribution/distribution/releases/latest
- https://github.com/distribution/distribution/releases/tag/v3.1.2
- https://api.github.com/repos/distribution/distribution/releases/tags/v3.1.2
- https://api.github.com/repos/distribution/distribution/license
- https://github.com/distribution/distribution/blob/v3.1.2/LICENSE
- https://hub.docker.com/v2/repositories/library/registry/tags?page_size=100&name=3
- https://hub.docker.com/v2/repositories/library/registry/tags/3.1.2
- https://github.com/distribution/distribution/blob/v3.1.2/docs/content/_index.md
- https://github.com/distribution/distribution/blob/v3.1.2/docs/content/about/_index.md
- https://github.com/distribution/distribution/blob/v3.1.2/docs/content/about/deploying.md
- https://github.com/distribution/distribution/blob/v3.1.2/docs/content/about/configuration.md
- https://github.com/distribution/distribution/blob/v3.1.2/docs/content/recipes/mirror.md
- https://github.com/distribution/distribution/blob/v3.1.2/docs/dockerhub.md
- https://github.com/distribution/distribution/blob/v3.1.2/BUILDING.md
- https://github.com/distribution/distribution/blob/v3.1.2/cmd/registry/config-dev.yml
- https://github.com/goharbor/harbor/blob/v2.16.0/Makefile
Source of this page: skills/airgap-architect/catalog/components/distribution-registry.toml.