Docker and OCI Repositories, Connectors, Registry Paths, Authentication, Layers, and Image Metadata: Configuration, Design Choices, and Tradeoffs

1. Native OCI versus Docker repository format

Nexus 3.94 introduced native OCI repositories in addition to the established Docker format. Both can serve container images to compatible tools, but native OCI is the better mental model when your artifact set includes image indexes, Helm charts, SBOMs, signatures, attestations, and OCI 1.1 referrers. Existing Docker repositories remain appropriate when you depend on Docker-format-specific features, Docker Hub index behavior, ECR proxy configuration, or an established estate you do not need to redesign.

2. Path-based routing versus dedicated connectors

Routing determines how a registry client maps a hostname/path/port to a repository. Path-based routing reduces listener/port sprawl and is Sonatype's preferred modern approach for Docker, and the only Cloud routing mode. Port connectors remain valid self-hosted endpoints but create operational overhead as repositories multiply. Reverse-proxy routing moves mapping/TLS/headers into another component, which can be useful but increases the diagnostic surface.

3. Mutable tags versus digest-pinned deployment

Tags are excellent for human workflows: 1.4, candidate, prod. But a deployment controller that resolves a mutable tag at two different times may receive two different manifests. For promotion and rollback evidence, record the digest. For critical runtime specifications, reference image@sha256:… when your platform supports it.

flowchart LR
T[candidate tag] --> M1[manifest digest A]
T -. can move if policy allows .-> M2[manifest digest B]
M1 --> C1[config digest]
M1 --> L1[layer digest]
M2 --> C2[config digest]
M2 --> L2[layer digest]

Tag immutability changes whether candidate can move. Current native OCI hosted repositories can enforce immutability with Disable redeploy. That is useful for version tags, but some organizations intentionally keep a mutable channel tag. If you need both patterns, separate repositories or tag conventions/policies rather than treating every tag as semantically identical.

4. Anonymous pull versus authenticated push

Public base-image caches may be readable anonymously on an isolated network, while internal images often require authenticated reads. Writes should be authenticated and least-privilege. For self-hosted Docker/OCI clients, the bearer-token realm must be active. A browser login session does not automatically supply CLI credentials.

Container clients persist credentials in config/auth files. In developer environments, use a credential helper/store where supported. In CI, inject a dedicated service credential via the CI secret mechanism and log in with --password-stdin. Never bake a registry password/token into a Dockerfile layer, image label, build argument that becomes image history, or committed config.json.

5. Proxying public versus private registries

A proxy improves availability and reduces repeated upstream transfers, but it also becomes a policy boundary. For Docker Hub, the classic Docker proxy format has explicit registry/index configuration. Native OCI proxy repositories can use https://registry-1.docker.io as a remote. Nexus 3.95 adds support for long-lived IAM and short-lived STS credentials when Docker proxy repositories authenticate to Amazon ECR; that is a version-specific feature, not a generic OCI assumption.

6. Group order and namespace ownership

Group order is a supply-chain decision. If learner-example/ch08-app is internal, hosted should precede the public proxy so a public collision cannot shadow it inside the group. That alone is not a complete defense: controlled network egress and routing rules should prevent clients from bypassing Nexus and pulling a same-named image directly from public registries.

7. Blob reuse versus repository identity

Content-addressed layers are naturally reusable when the same digest appears in multiple images. Reuse reduces storage and transfer, but it does not collapse repository policy. Two repositories can point at content that shares blob bytes while still having different authorization, retention, tag, or routing semantics. Never “optimize” storage by manually deduplicating or deleting Nexus blob files.

8. Availability versus freshness

A proxy cache can keep previously fetched public image content available during an upstream outage. That does not guarantee an uncached tag or newly moved tag can resolve. A digest-pinned image already cached in Nexus has a stronger availability story than a moving tag whose current manifest has never been cached. Record whether an incident affects name resolution/metadata, manifest retrieval, or layer retrieval rather than saying “Docker is down.”

9. Worked design scenario

A 40-developer team uses internal images under corp/*, pulls open-source bases from Docker Hub, deploys to Kubernetes, and wants one read endpoint. They have Nexus Community on a private VM and no requirement for SSO or HA yet.

10. Decision checklist

• Which image namespaces are authoritative internally?
• Which upstream registries must be proxied, and which credentials do those upstreams require?
• Are tags immutable, channel-like, or mixed by policy?
• Will runtime deployment record/pin a manifest digest?
• Which routing mode is supported by your exact Nexus version/edition and client fleet?
• Where are client credentials stored and rotated?
• Can any build/runtime bypass Nexus and reach public registries directly?
• What evidence proves which repository member served an image during an incident?

Knowledge check

Official references and version notes

• Nexus Repository Download and 3.95.0 release notes — current downloadable self-hosted baseline for this chapter.
• Sonatype: Docker Registry — Docker registry paths, routing methods, API support, and self-hosted connector guidance.
• Sonatype: Docker Authentication — Docker Bearer Token Realm, login behavior, and anonymous-access prerequisites.
• Sonatype: OCI Repositories, Create an OCI Repository, and Configure OCI Repository.
• Sonatype: OCI CLI Usage — Docker/Podman/OCI-compatible client examples.
• Sonatype: Proxy Repository for Docker and reverse-proxy strategies.
• Docker: docker image pull — tag versus digest pulls and layer reuse.
• OCI Image Manifest Specification and OCI Image Configuration.

Version-sensitive statements were rechecked against Sonatype, Docker, and OCI primary documentation on 2026-08-26. The mandatory lab assumes self-hosted Nexus Repository Community Edition 3.95.0, Java 21 on the Nexus side, native OCI repositories introduced in Nexus 3.94.0, and a current Docker-compatible client. Record docker version or podman version locally; client behavior evolves independently of Nexus. Re-check the live release and format documentation before executing the lab.