Docker and OCI Repositories, Connectors, Registry Paths, Authentication, Layers, and Image Metadata: Concepts, Architecture, and Mental Model

1. The practical problem: an image is not one file

Chapter 07 treated an npm package as metadata plus a tarball. Container images add another content-addressed graph. A tag such as academy-app:1.0.0 is a human-friendly reference. A registry resolves that reference to a manifest (or, for multi-platform content, an image index/manifest list). The manifest points to an image configuration object and one or more filesystem layers by digest. Each descriptor carries a media type, digest, and size.

That separation matters operationally. If a tag changes, the digest can change even though the tag text does not. If two images share a layer digest, the registry can reuse the same stored blob. If a client gets a 401 first, that can be a normal authentication challenge rather than a bad password. If the wrong routing method is used, the request may never reach the intended repository even though Nexus is healthy.

2. Name, tag, digest, manifest, config, and layer

The OCI image specification deliberately separates manifest, configuration, and layer descriptors. Docker uses compatible content-addressed behavior. This is why “the image checksum” is imprecise: several digests can exist in the graph, and a local image ID is not always the same concept as the remote manifest digest printed by a push or pull.

3. Hosted, proxy, and group still have distinct jobs

The repository types from Chapter 04 still apply, but the protocol is now the OCI/Docker registry API. A hosted repository stores content your organization pushes. A proxy repository fronts an upstream registry such as Docker Hub. A group combines hosted and proxy members behind one read endpoint. Current native OCI repositories support all three types; when the same image path exists in more than one group member, the first member in configured order wins.

flowchart TD
C[Docker or Podman client] -->|/v2 bearer-token flow| G[OCI group path]
G -->|internal path first| H[OCI hosted]
G -->|miss then public| P[OCI proxy]
P --> U[Docker Hub or OCI upstream]
H --> DB[(Nexus database metadata)]
P --> DB
H --> BS[(blob store: manifests configs layers)]
P --> BS
I[Identity / realm] -->|token scope| C

The first arrow is not “download one tar file.” The client performs Registry API calls for manifests/config/layers and may issue HEAD requests to ask whether a blob already exists. The group routes the logical image request. Hosted/proxy repository records and blob content are persisted separately in Nexus database and blob storage. The identity service participates in the bearer-token challenge so the client receives only the requested repository scope.

4. Routing is part of the protocol contract

Sonatype currently documents four Docker routing strategies: path-based routing (preferred), subdomain routing, reverse-proxy remapping, and legacy port connectors. Native OCI repositories likewise support path-based, subdomain, and port addresses. In self-hosted Community, path-based and port routing are available; OCI subdomain routing requires Pro. Path-based routing avoids multiplying connector ports and wildcard certificates.

5. Authentication is a challenge-and-token exchange

For a self-hosted OCI/Docker client, enable the appropriate bearer-token realm before expecting client login to work. A Registry API request can legitimately return 401 Unauthorized with a WWW-Authenticate challenge. The client uses its saved login credential to request a short-lived scoped bearer token, then retries the registry operation.

sequenceDiagram
participant C as Container client
participant R as Nexus /v2 registry endpoint
participant A as Nexus token realm
C->>R: GET/HEAD manifest or blob
R-->>C: 401 + WWW-Authenticate challenge
C->>A: request token with repository scope
A-->>C: scoped bearer token
C->>R: retry with Bearer token
R-->>C: manifest/blob or authorization denial

Login state is client-side credential material, normally under Docker's ~/.docker/config.json or a Podman auth file. The lab uses a disposable auth file/config directory. Do not confuse browser SSO with CLI registry authentication, and do not embed passwords in image names, Dockerfiles, scripts, or shell history.

6. Tags are pointers; digests are identities

Docker documentation explicitly allows pulling by tag or digest. A tag can be reassigned unless the registry policy prevents it; a digest identifies exact content. Production deployment evidence should record the resolved manifest digest even when operators also use a friendly tag. A tag such as candidate communicates a channel. A digest such as sha256:… communicates which manifest bytes were selected.

7. Docker repository format versus native OCI repository format

Nexus has long supported Docker repositories and supports OCI 1.0.x images inside Docker repositories. Starting with 3.94.0, Nexus also provides a native OCI format with hosted/proxy/group recipes, OCI 1.1 Referrers API support, multi-architecture images, signatures/SBOM/attestation artifacts, and tag-immutability policy. Docker, Podman, Helm, ORAS, Cosign, Syft, Crane, and Skopeo can use OCI repositories because they speak OCI-compatible registry protocols.

This chapter uses native OCI for its mandatory lab because it is current, Community-compatible, and exposes modern image-plus-supply-chain metadata semantics without requiring a paid feature. Docker repository behavior remains important for existing estates, Docker Hub-specific index behavior, ECR proxy support, and migration compatibility.

8. Inspect before mutation

Before creating or pushing anything, record the Nexus version, repository list, active realm state, and the container client version. In the Nexus UI, inspect Settings → Repository → Repositories and Settings → Security → Realms. If you have a read-only API identity, capture GET /service/rest/v1/repositories rather than guessing names/types.

export NX_URL="http://127.0.0.1:8081"
curl -fsS "$NX_URL/service/rest/v1/status" | tee nexus-status.txt

docker version 2>/dev/null || true
podman version 2>/dev/null || true

printf 'Inspect in Nexus UI:
'
printf '  Settings -> Repository -> Repositories
'
printf '  Settings -> Security -> Realms
'
printf '  System / support view -> exact Nexus version
'

9. State map: what changes when an image is pushed?

10. Why this matters in DevOps

Image registries sit directly on the release path. A deployment system that records only app:latest, lets clients bypass Nexus, or treats a local image ID as repository evidence cannot reliably answer “what exact bytes ran?” A production operating model therefore records the Nexus route, repository type, manifest digest, tag-at-time-of-release, authorization identity, and relevant build/provenance evidence.

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.