Production Capstone: Design, Secure, Automate, Migrate, and Recover an Enterprise Artifact Platform: Requirements, Constraints, and Target Architecture

1. The capstone problem: production readiness is a system property

Imagine a company called Learner Example Engineering. Its build teams consume public Maven and npm packages, publish internal Java and JavaScript releases, store generic release evidence, and occasionally distribute container images. CI must publish once, downstream environments must consume controlled immutable identities, developers should not bypass the repository boundary, and operators need tested recovery.

If you configure repositories without answering who owns namespaces, what state is authoritative, how credentials are scoped, what happens during upstream/storage failure, or how a restore is validated, the installation is not yet a production platform.

2. Requirements first: write measurable statements

3. Read-only inspection before design claims

Before creating a repository, role, cleanup policy, or task, prove what instance you are actually operating. Record the current Nexus version and edition from the UI/system information, the Java runtime, database type, blob-store topology, repository inventory/type/format, active realms/anonymous-access posture, scheduled-task state, and a small logs/metrics baseline. The exact running OpenAPI document is the source of truth for write schemas.

NEXUS_URL='http://127.0.0.1:8081'
# Readiness only; this does not prove external DB/blob health.
curl --fail --silent "$NEXUS_URL/service/rest/v1/status"

# Authenticated read-only inventory for a disposable lab identity.
curl --fail --silent --user "$NEXUS_USER:$NEXUS_PASSWORD" \
  "$NEXUS_URL/service/rest/v1/repositories"

# Capture the running API contract before automation writes.
curl --fail --silent --user "$NEXUS_USER:$NEXUS_PASSWORD" \
  "$NEXUS_URL/service/rest/swagger.json" -o capstone-swagger.json

Interpret the evidence carefully: application status does not validate PostgreSQL, disk, or blob-service health. A repository list does not prove authorization is least privilege. The purpose of this snapshot is to make later changes causally attributable and version-aware.

4. Target repository topology: one pattern per ecosystem

The capstone uses a small, explainable topology rather than dozens of repositories:

Hosted repositories are authoritative publication targets. Proxies mediate/cache upstream content. Groups are read aggregation. CI never deploys to a proxy or group.

5. The production-state map

flowchart LR
  DEV[Developer and \nbuild clients] --> TLS[TLS reverse proxy or load balancer]
  CI[CI service identity] --> TLS
  TLS --> NX[Nexus Repository nodes]
  NX --> DB[(PostgreSQL metadata and configuration)]
  NX --> BLOB[(Blob storage)]
  NX --> UP[Public upstream registries]
  IDP[Identity provider] --> NX
  NX --> EVT[Webhooks and automation]
  NX -. optional licensed policy .-> IQ[IQ / Repository Firewall]
  BK[Backup system] --> DB
  BK --> BLOB
  NX --> OBS[Logs metrics support evidence]

Every arrow means a dependency, protocol, credential, latency budget, or failure mode. The database and blob store together form repository state; external identity is a dependency rather than repository content; logs/metrics are evidence rather than truth by themselves; backup copies must preserve coherent database/blob state.

6. Community learning target versus production target

7. Capacity and database gate

Current Sonatype requirements still distinguish the small embedded-H2 profile from supported production growth. H2 is the default for new installations but has documented workload limits and is not supported for container-based deployments. External PostgreSQL is the current production recommendation. The architecture therefore records why a database is selected and the migration trigger, rather than treating H2 as interchangeable with PostgreSQL.

8. Identity and authorization model

Use four identities in the design:

• platform-admin: emergency/administrative configuration; not a CI credential.
• capstone-publisher: create/upload only to the internal hosted publication namespaces required by CI.
• capstone-reader: read/browse only through approved group/hosted endpoints.
• automation-reconciler: narrowly scoped configuration API identity; no artifact publication unless explicitly needed.

Browser SSO, package-client credentials, and automation credentials remain different authentication contexts even if they map to related roles.

9. Network and namespace boundary

Clients should have one documented path per ecosystem. If an internal scope can fall back to a public registry, dependency confusion remains possible even if Nexus itself is correctly configured. Production design therefore includes package-client configuration, routing rules/content controls where applicable, and network/egress policy outside Nexus. The repository manager cannot enforce traffic it never sees.

10. Build-once release flow

flowchart TD
  SRC[Source commit] --> BUILD[CI build ID]
  BUILD --> ART[Immutable artifact + SHA-256 or digest]
  ART --> DEVREP[Hosted intake / release-candidate repository]
  DEVREP --> VERIFY[Tests policy evidence]
  VERIFY --> PROMOTE[Move or copy exact artifact]
  PROMOTE --> REL[Release repository]
  REL --> CONSUME[Consumers pin version or digest]

Native Nexus staging/promotion is a Pro capability. The Community-compatible learning path proves the same invariant with synthetic bytes: release stages may transfer the already-built artifact but must not rebuild source and call the result “promotion.”

11. Recovery, migration, upgrade, and HA are separate controls

• Backup/restore answers: can we recover coherent state after deletion/corruption?
• Migration answers: can we move supported source state to a supported target?
• Upgrade answers: can we change Nexus/runtime version while satisfying crossed-version gates?
• HA answers: can service continue through selected node/failure-domain failures?

HA does not restore yesterday's uncorrupted data. Backup does not provide active-node availability. Migration is not a backup. A production design needs the subset required by the business objectives, with each control tested independently.

12. Architecture acceptance record

{
  "platform": "learner-example-artifact-platform",
  "referenceVersion": "3.95.2-01",
  "runtime": "Java 21",
  "mandatoryLabEdition": "Community",
  "productionDatabase": "PostgreSQL",
  "namespaces": ["com.example", "@learner-example"],
  "rpoMinutes": 30,
  "rtoMinutes": 60,
  "releaseIdentity": "coordinate + SHA-256/digest + build ID",
  "directPublicBypass": "prohibited by client/network governance",
  "paidExtensions": ["optional Pro HA", "optional Staging", "optional Firewall/IQ"]
}

13. Architecture challenge

A team asks for three independent Nexus servers, each with its own H2 database and local blobs, behind round-robin DNS. Is that HA?

No. Those nodes have divergent authoritative state. Current Nexus HA is a Pro topology with coordinated nodes sharing supported database/blob state behind a load balancer; three independent installations are three different repositories, not one highly available service.

Knowledge check

Summary and next step

The capstone now has measurable requirements, a minimal multi-format topology, explicit state ownership, trust boundaries, edition choices, build-once release identity, and independent availability/recovery controls.

Lesson 2 turns this architecture into reproducible desired state, disposable repositories, least-privilege identities, client boundaries, synthetic publication, promotion evidence, and operator runbooks.

Official references and version notes

• Sonatype: Nexus Repository documentation — current self-hosted product entry point and supported-format documentation.
• Sonatype: 2026 self-hosted release notes — release-specific changes and known-issue/upgrade guidance.
• Sonatype: Self-Hosted Feature Matrix — Community versus Pro capability boundary.
• Sonatype: System Requirements — Java 21, H2 workload limits, PostgreSQL guidance, sizing, file handles, and deployment constraints.
• Sonatype: Repository Types — hosted, proxy, and group responsibilities.
• Sonatype: Content Selectors — fine-grained content authorization concepts.
• Sonatype: Cleanup Policies — retention criteria, preview/evaluation, deletion semantics, and blob reclamation boundary.
• Sonatype: REST and Integration API — documented REST/OpenAPI automation boundary.
• Sonatype: Webhooks — repository/global events and delivery semantics.
• Sonatype: Staging — current Pro-only staged component movement/promotion capability.
• Sonatype: Repository Firewall — separately licensed IQ-powered policy integration and supported Nexus editions.
• Sonatype: Prepare a Backup — coordinated database/blob backups and node-ID preservation.
• Sonatype: Database migration — current migration tooling and compatibility gates.
• Sonatype: Instance Migrator — current source/target migration workflow and constraints.
• Sonatype: Upgrade Paths — version thresholds and mandatory crossed-version procedures.
• Sonatype: Rolling Upgrades in HA — Pro/HA rolling-upgrade behavior and mixed-mode constraints.
• Sonatype: HA system requirements — Pro-only active-node topology, shared PostgreSQL/blob state, and failure-domain requirements.
• Sonatype: Logging — application/request/outbound/audit/JVM evidence.
• Sonatype: Prometheus — current metrics endpoint and privilege boundary.
• Sonatype: Support Features — support ZIP generation and evidence handling.