Artifact Repository Foundations, Package Supply Chains, Components, Assets, and Repository Managers: Concepts, Architecture, and Mental Model

1. The problem: Git does not deliver binary dependencies

A delivery system must preserve more than source commits. A build consumes compilers, plugins, base images, libraries, package metadata, and organization-owned components; it produces JARs, packages, archives, images, reports, and deployable bundles. Those objects need stable identities and controlled distribution after the source commit that produced them already exists.

Source control is excellent at preserving reviewable source history. It is a poor substitute for a package protocol, binary retention policy, dependency cache, or release distribution endpoint. Similarly, a developer's local Maven, npm, pip, NuGet, or container cache improves one workstation but is not a governed organization-wide source of truth. A repository manager occupies that missing boundary.

Think of Nexus Repository as an artifact traffic control and persistence layer. Producers upload organization-owned components to hosted repositories. Consumers fetch internal and external components through protocol-aware endpoints. Proxy repositories mediate remote ecosystems. Group repositories present several same-format repositories behind one client URL. The repository manager adds central policy, observability, retention, access control, and durable storage around those flows.

flowchart LR
SRC[Source repository] --> BUILD[Build or package client]
BUILD -->|publish internal| HOSTED[Nexus hosted repository]
CLIENT[Consumer client] --> GROUP[Nexus group endpoint]
GROUP --> HOSTED
GROUP --> PROXY[Nexus proxy repository]
PROXY --> UPSTREAM[Public or private upstream]
HOSTED --> STATE[(Database metadata plus blob bytes)]
PROXY --> STATE
GROUP --> CLIENT

The arrows are deliberately directional. A producer publishes internal output to a hosted repository. A consumer reads through a group or individual endpoint. A proxy obtains remote content and caches it. The database and blob store are implementation state behind the service; package clients must not manipulate them directly.

2. Build the vocabulary before touching the UI

Repository discussions become dangerous when several words are treated as synonyms. Nexus uses a generic model so many ecosystems can fit one administration platform, but each ecosystem retains its own coordinate and metadata rules.

A Maven component often has several assets: the binary JAR, its POM, a sources JAR, a Javadoc JAR, and checksum/signature files. By contrast, Sonatype documents Raw repositories as treating each file as a separate component. This is why “one component equals one file” is not a safe universal model.

3. Coordinates are the address; bytes are the evidence

Coordinates answer “which logical release?” A digest answers “which exact bytes?” A production artifact identity normally needs both. A release named 1.4.0 that can be silently overwritten is not operationally immutable even though the version string looks stable.

Logical identity
  format: maven2
  group: com.example.academy
  name: ledger-api
  version: 1.4.0

Byte identity
  asset: ledger-api-1.4.0.jar
  sha256: <recorded digest from your controlled build/publish flow>

Traceability
  source commit: <commit SHA>
  build run: <CI/build ID>
  repository: <authoritative hosted repository name>

The repository manager should preserve the relationship between these layers. “It downloads” only proves reachability. “The coordinate exists” only proves an index entry. “The checksum matches the accepted candidate” is stronger for byte identity. A complete release story additionally records who produced it, from what source/tool inputs, under what policy, and where the authoritative copy lives.

4. Hosted, proxy, and group are different authorities

A group is not a magical cross-format “universal protocol.” Maven, npm, PyPI, NuGet, OCI and other clients speak different protocols. Nexus can be one organizational artifact hub while still exposing format-specific repository endpoints. Group ordering also matters: Nexus searches members sequentially, so internal hosted repositories are commonly placed ahead of external proxies when the namespace design calls for that behavior.

The most costly conceptual error is treating a proxy cache as the canonical home of your release. A proxy's cached content exists because a remote was requested; cache eviction or upstream policy can alter availability. Internal release output belongs in a hosted repository whose retention and redeploy policy you control.

5. The state model: configuration, database, blobs, clients, and caches

flowchart TB
REQ[HTTP or package request] --> APP[Nexus Repository application]
APP --> AUTH[Authentication and authorization]
APP --> CONF[Repository configuration]
APP --> DB[(Database metadata)]
APP --> BLOB[(Blob store bytes)]
APP --> LOGS[Logs tasks and metrics]
CLIENTCACHE[Client local cache] -. separate .-> REQ
UPSTREAM[Remote upstream] -->|proxy miss or revalidation| APP

The database and blob store are complementary. Database records describe repository/component/asset state; blob stores hold the binary payloads and blob-level metadata. A backup or recovery procedure must reason about both as a consistent system. Editing database rows or blob files directly is not a troubleshooting shortcut and is outside this chapter's safe lab boundary.

The client has separate state. Maven's local repository, npm cache, pip cache, NuGet global packages folder, Docker/OCI local content, and client config files can make a request succeed even when Nexus was never contacted. When diagnosing repository behavior, record whether the client cache was warm and prove the HTTP path rather than assuming a successful package command traversed Nexus.

6. Draw the trust boundaries explicitly

Every network hop or executable package source is a trust decision. At minimum, identify these boundaries:

• Producer → hosted repository: who may publish, which namespace, which versions, and whether redeploy is allowed.
• Consumer → Nexus: TLS, authentication, least-privilege read access, and the exact endpoint configured in the client.
• Nexus proxy → upstream: remote URL ownership, HTTPS validation, upstream credentials, routing rules, namespace policy, cache freshness, and outage behavior.
• Nexus application → database/blob storage: filesystem/object-store/database permissions, latency, capacity, consistency, backup, and recovery.
• CI → Nexus: scoped non-human credentials, secret handling, publish/read separation, and artifact identity evidence.

Nexus Community Edition already provides the core repository-manager path, REST APIs, component search, custom access controls, content selectors, routing rules, LDAP, external PostgreSQL support, and other substantial capabilities. Current self-hosted Pro-only features include items such as HA deployment options, SAML, user tokens, staging/build promotion, and some storage/replication capabilities. Do not design a mandatory lab around a Pro-only control.

7. Inspect first: prove the instance and endpoint state read-only

Shell note: executable blocks in this lesson are POSIX/Bash examples. On Windows, use curl.exe or Invoke-RestMethod, Get-FileHash -Algorithm SHA256 for hashes, and private temporary credential storage. The Nexus HTTP endpoints and repository semantics do not change.

Use a disposable local instance when available. The examples use loopback and do not embed a password. If your training instance requires authentication, keep credentials only in private temporary state and remove them immediately after use.

export NX_URL="http://127.0.0.1:8081"

# 1) Can the application serve reads?
curl -i "$NX_URL/service/rest/v1/status"

# 2) What repository endpoints exist? Authentication may be required.
curl -fsS "$NX_URL/service/rest/v1/repositories" | python -m json.tool

# 3) The instance exposes its OpenAPI/Swagger document without needing
#    you to guess version-specific fields.
curl -fsS "$NX_URL/service/rest/swagger.json" -o nexus-swagger.json

# 4) For a repository you are allowed to inspect:
curl -fsS "$NX_URL/service/rest/v1/components?repository=maven-central" \
  | python -m json.tool
curl -fsS "$NX_URL/service/rest/v1/assets?repository=maven-central" \
  | python -m json.tool

Expected evidence is structural, not a magic exact JSON blob: status should return HTTP 200 when reads are serviceable; repository results identify names, formats, types and URLs; component results group logical packages; asset results expose individual paths/download URLs/checksums. If anonymous access is disabled, a 401/403 is useful evidence about authorization—not a reason to weaken the instance.

8. Why this matters in DevOps

A repository manager changes the delivery contract. CI no longer depends on every developer or agent independently reaching public ecosystems. Internal artifacts have a durable publish destination. Consumers can be directed through controlled endpoints. Access, routing, retention, checksums, and observability become centralized operational decisions instead of hidden workstation state.

That does not make builds automatically reproducible or supply chains automatically safe. Reproducibility still depends on pinned inputs and deterministic builds; security still depends on publisher identity, upstream governance, verification, vulnerability/malware controls, and credential hygiene. Nexus supplies a boundary where those controls can be applied and evidenced.

9. Common wrong mental models

• “GitHub Releases is the same thing as a repository manager.” A release-asset page can distribute files, but package clients expect ecosystem metadata/protocols and organizations need proxy/group/access/storage lifecycle semantics.
• “The local Maven/npm/pip cache is our repository.” A per-machine cache is not centrally governed, backed up, permissioned, or an authoritative publication target.
• “Everything in Nexus is one file.” Component-to-asset cardinality depends on the format.
• “A 200 download means trusted.” It only proves the server delivered bytes.
• “One Nexus URL can be pasted into every package manager.” Clients require format-specific protocol endpoints; a single Nexus service can expose many such endpoints.
• “If something is wrong, delete blobs or database rows.” Never use direct internal-state deletion as a first-line repair.

10. Guided read-only checkpoint

Scenario: You inherit a training Nexus instance at 127.0.0.1. Before anyone creates, deletes, uploads, or changes a repository, produce an architecture note that answers five questions: What release/runtime is in use? Which repositories are hosted/proxy/group? Which endpoint would a producer write to? Which endpoint would a consumer read from? Which state belongs to Nexus versus the client?

1. Record the Nexus release shown by the training environment and compare it with the current 3.95.2 release-note baseline.
2. Call the status and repositories APIs. Save sanitized output under a disposable evidence/ch01-l1/ directory.
3. Pick one repository that contains content and list both components and assets. Explain why the counts need not match.
4. Draw the request path from one client to the repository endpoint and, if it is a proxy, onward to its upstream.
5. Mark every credential, network, storage, and upstream boundary. Do not change anything.

Verification checklist: repository type and format are not confused; no production URL or secret is recorded; client-local cache is represented separately; database metadata and blob bytes are represented separately; a successful download is not labeled “trusted” without additional evidence.

Cleanup: delete only the local evidence directory if you do not want to retain it. There is no Nexus mutation to roll back in this lesson.

Knowledge check

11. Summary

You now have the core operating model: producers publish governed internal output to hosted repositories; proxies mediate remote ecosystems; groups aggregate same-format members for consumers; components are logical package identities; assets are stored/downloaded files; Nexus database metadata and blob bytes are separate from client caches; checksums prove byte identity rather than trust; and every publish, proxy, credential, upstream, and storage hop is a trust boundary.

Official references and version notes

• Nexus Repository 3.95.0–3.95.2 release notes — 3.95.2 was released August 21, 2026 and is the current self-hosted baseline used in this chapter.
• Nexus Repository system requirements — current Java, H2/PostgreSQL, storage, memory, operating-system, and deployment constraints.
• Repository Manager Concepts — components, assets, coordinates, repository formats, proxy behavior, routing, and repository-manager purpose.
• Repository Types — hosted, proxy, and group semantics and group ordering.
• Self-Hosted Nexus Repository Feature Matrix — Community-versus-Pro capability boundaries.
• Nexus Repository API Reference — current REST API surface and embedded Swagger model.
• Status API — readiness and writable-state HTTP checks.
• Search API — component/asset search and the SQL-search behavior used by current releases.
• Components API — listing and uploading components to hosted repositories.
• Assets API — listing and inspecting individual assets.

Version-sensitive statements were rechecked against Sonatype primary documentation on 2026-08-26. The mandatory path remains self-hosted, Community/free-compatible, and disposable; production credentials, production repositories, and paid-only capabilities are outside the lab boundary.