Hosted, Proxy, and Group Repositories: Design Patterns, Routing, Caching, and Promotion Flows: Concepts, Architecture, and Mental Model

1. The practical problem: one URL cannot mean every repository job

Chapter 03 taught you to inspect a repository before mutating it. The next operational question is where should each request go? A build has at least two very different intents. A publisher wants to create organization-controlled state. A consumer wants to resolve content that may come from the organization, a trusted upstream, or both. If those intents are hidden behind arbitrary URLs, teams eventually upload to the wrong place, bypass policy, or mistake cached public content for an internal release.

Nexus Repository makes the routing intent explicit through three repository types. A hosted repository is an authoritative storage location managed by your organization. A proxy repository is a controlled access point to a remote repository: it stores cacheable remote content locally as requests arrive. A group repository is an ordered read view over compatible member repositories. A group does not become a fourth authoritative copy of every member.

2. The topology mental model

flowchart LR
  CI[CI publisher] -->|write| H[Hosted repository]
  DEV[Developer / build] -->|read| G[Group repository]
  G -->|member 1| H
  G -->|member 2| P[Proxy repository]
  P -->|cache miss or refresh| U[Public upstream]
  H --> DB[(Database metadata)]
  H --> B[(Blob bytes)]
  P --> DB
  P --> B
  G --> DB

The CI → hosted arrow is a publication path. Nexus records component/asset metadata in database state and stores binary payloads in the configured blob store. The consumer → group arrow is a read path. The group evaluates its members in configured order. A request that reaches the proxy may be answered by already cached Nexus state or may require a remote check/fetch. The proxy then records its own cached metadata and blob content. The group itself primarily owns configuration and routing metadata; it does not pre-copy the members.

This is why “the artifact is in Nexus” is too vague for production work. You should be able to say which repository is authoritative, which repository cached it, which group exposed it, which endpoint the client used, and which privilege path allowed the request.

3. Hosted repositories: organization-controlled origin

A hosted repository is where your organization intentionally publishes content. “Hosted” describes authority, not merely physical disk location. Its write policy, format rules, version policy, privileges, blob-store selection and retention choices define what publication means. For Maven, a release-oriented hosted repository can be configured so an already-deployed coordinate is not casually overwritten.

Hosted state also establishes a clean trust statement: our workflow accepted these bytes into this controlled repository. That statement still does not prove the bytes are vulnerability-free or cryptographically trusted; later chapters add signatures, provenance, SBOM and policy concepts.

4. Proxy repositories: cache plus upstream policy boundary

A proxy repository has a configured remote storage URL. When a client asks Nexus for content that is not locally reusable, Nexus can contact that remote, receive the content, record metadata, and cache the binary. Subsequent requests may be served without downloading the same bytes again, subject to the repository’s cache and remote-health rules.

Several clocks matter. Maximum component age and maximum metadata age govern how long certain cached information can remain before Nexus checks the remote again. Negative cache remembers a remote “not found” result for a configured time so repeated misses do not continuously hit the upstream. Auto-blocking is a remote-health behavior: Nexus can temporarily block a failing remote while continuing to use cached content that is already present.

These are not your Maven local repository, npm cache, pip cache, Docker layer cache, browser cache, or a reverse proxy cache. When diagnosing “it was cached,” identify the exact cache layer.

5. Groups are ordered read views

A group presents compatible member repositories through one URL. Members are searched in order. If two members can satisfy the same path or coordinate, ordering can determine which content wins. Current Nexus Repository also allows group membership to be transitive: a group can contain another compatible group. That convenience increases the need to document the effective order and avoid loops or surprising namespace overlap.

Authorization follows the request path too. A privilege that grants access through the group applies to its members transitively for requests made to the group. That does not automatically grant direct access to each member URL. This lets administrators expose a curated read view while keeping member repositories less directly visible.

6. Separate read endpoints from publish endpoints

A practical topology gives consumers a small number of stable group URLs and gives publishers explicit hosted URLs. That separation makes intent machine-checkable. If a pipeline is configured with a group URL in its publication settings, the failure is a useful signal: the pipeline is trying to write through a read abstraction.

The same separation improves incident response. When a bad candidate appears, you know whether to inspect the hosted publication target, the group order, the proxy cache, or the upstream. When developers report inconsistent results, you can compare their client endpoint and cache against the group’s effective topology instead of searching every repository blindly.

7. Promotion means preserving artifact identity

flowchart TD
  SRC[Source commit] --> B[Build once]
  B -->|SHA-256 A| DEV[Dev / incoming hosted]
  DEV -->|copy accepted bytes| REL[Release hosted]
  REL -->|SHA-256 A| RG[Release read group]
  SRC -. later rebuild .-> B2[New build environment]
  B2 -. may produce SHA-256 B .-> BAD[Not the same accepted artifact]

Promotion is a lifecycle decision about an already-built artifact. The defensible pattern is: build once, record its coordinate and checksum/digest, publish it to a candidate location, perform required checks, and then move or copy the same accepted bytes to the release stage using a supported mechanism. A later rebuild from the same source commit is a new build. Even if its version string is identical, toolchains, timestamps, dependencies or nondeterministic inputs can change its bytes.

Nexus Repository Pro includes staging/build-promotion capabilities. This course cannot require those paid features, so the mandatory Community lab demonstrates the invariant directly: download the accepted artifact from the dev hosted repository, hash it, upload those exact bytes to a disposable release hosted repository, then hash the release retrieval. The learning objective is identity preservation, not imitation of every Pro workflow feature.

8. Read-only inspection before topology changes

Before you create, reorder or invalidate anything, capture what Nexus currently believes. The repository inventory is a safe first check. An authenticated operator can also inspect repository settings and use the UI to record group members and proxy cache fields.

# POSIX/Bash. Windows PowerShell guidance follows this block.
LAB="$HOME/nexus-ch04-lab"
NX_URL="http://127.0.0.1:8081"
mkdir -p "$LAB/evidence" "$LAB/payload" "$LAB/promote"
umask 077
read -rsp "Disposable Nexus admin password: " NX_PASS; printf "\n"
printf 'machine 127.0.0.1 login admin password %s\n' "$NX_PASS" > "$LAB/nexus.netrc"
unset NX_PASS
NETRC="$LAB/nexus.netrc"

# Never print, commit, or reuse this temporary credential file.

curl -fsS "$NX_URL/service/rest/v1/status"   | tee "$LAB/evidence/01-status.txt"

curl --fail-with-body --silent --show-error --netrc-file "$NETRC"   "$NX_URL/service/rest/v1/repositories"   | tee "$LAB/evidence/02-repositories.json"

curl --fail-with-body --silent --show-error --netrc-file "$NETRC"   "$NX_URL/service/rest/v1/repositorySettings"   | tee "$LAB/evidence/03-repository-settings.json"

Save the evidence rather than relying on a screenshot alone. The inventory tells you names, formats, types and URLs that are visible to the caller. The settings view gives richer configuration to an authorized administrator. Neither call mutates repository content.

9. Why this matters in DevOps

Repository topology is part of delivery architecture. It determines the single place a pipeline may publish, the upstreams a build may contact, the internal namespaces that must never fall through to public registries, the cache that can keep builds working during an upstream interruption, and the evidence used to prove a released artifact is the exact accepted build output.

Knowledge check

10. Summary

Hosted, proxy and group repositories are different responsibilities in one routing graph. The safe baseline is explicit hosted write targets, ordered group read targets, controlled proxies, documented cache behavior and exact-byte promotion. The next lesson builds that graph on a disposable Community instance.

Official references and version notes

• Download Nexus Repository and Nexus Repository 3 Versions Status — re-check the self-hosted release line before running the pinned lab.
• Repository Types — hosted, proxy and group semantics, nested/transitive groups, ordered member lookup, and direct-member privilege boundaries.
• Configurable Repository Fields — proxy remote storage, component/metadata age, negative cache, blocking, and auto-blocking.
• Repository Actions — current cache invalidation behavior and what it does not delete.
• Repositories API — repository inventory and format/type-specific repository configuration endpoints.
• Components API, Assets API, and Search API — upload plus independent component/asset evidence.
• Maven Repositories — Maven hosted/proxy/group configuration semantics and Central proxy use.
• Routing Rules — controlling proxy requests and preventing internal namespaces from falling through to public remotes.
• Staging and the current feature matrix — Nexus staging/build-promotion is a Pro capability; the mandatory Community lab uses exact-byte copy semantics instead.

Version-sensitive statements were rechecked against Sonatype primary documentation on 2026-08-26. The mandatory path pins the same self-hosted Community lab baseline used by Chapters 02–03: Nexus Repository 3.94.1-06, Java 21, one loopback single-node instance, embedded H2 only for disposable learning, and the default file blob store. Production database/storage decisions are deferred to Chapter 05. Re-check the current download/status/release-note pages before execution.