Checkpoint Lab — Nexus Repository Editions, Deployment Models, Architecture, Installation, and Java Runtime Planning

1. Scenario and success criteria

You are preparing a proof-of-concept artifact service for a development team. Before any package-format work, you must prove that the service has a supported runtime, an explicit persistence boundary, a safe process/network identity, a known database/blob model, and repeatable restart behavior. The handoff packet must let another engineer reconstruct what existed without receiving your admin password.

2. Setup and exact assumptions

• Nexus: self-hosted Community Edition, pinned lab archive 3.94.1-06 because that is the current official downloadable baseline at review time.
• Runtime: supported bundled/current Java 21 path; do not force an external JVM.
• Database: embedded H2, valid only for this small, non-containerized, disposable lab.
• Blobs: default local filesystem blob storage inside the disposable data tree.
• Network: 127.0.0.1:8081 only; no public/LAN exposure.
• Process: ordinary disposable user, never root/Administrator merely to make startup succeed.
• Paid features: none. HA, SAML, user tokens, resilient deployments and Pro-only capabilities are architecture notes only.

LAB="$HOME/nexus-ch02-checkpoint"
test ! -e "$LAB" || { echo "Refusing: checkpoint path already exists" >&2; exit 1; }
mkdir -p "$LAB"/{evidence,instance}
cd "$LAB"

uname -a | tee evidence/01-os.txt
ulimit -n | tee evidence/02-file-limit.txt
df -h . | tee evidence/03-disk.txt
free -h 2>/dev/null | tee evidence/04-memory.txt || true

Download the 3.94.1-06 archive from Sonatype's official download/archive page and verify its published checksum. Copy it into $LAB/nexus-3.94.1-06.tar.gz. The evidence packet should record the verified hash, not an untrusted mirror URL.

3. Extract and preconfigure the safe listener

cd "$LAB/instance"
tar xvz --keep-directory-symlink -f ../nexus-3.94.1-06.tar.gz
NX_INSTALL="$(find "$PWD" -maxdepth 1 -type d -name 'nexus-*' -print -quit)"
NX_DATA="$PWD/sonatype-work/nexus3"
test -n "$NX_INSTALL"

mkdir -p "$NX_DATA/etc"
cat > "$NX_DATA/etc/nexus.properties" <<'EOF'
application-host=127.0.0.1
application-port=8081
nexus-context-path=/
EOF
chmod 600 "$NX_DATA/etc/nexus.properties"
printf 'install=%s\ndata=%s\n' "$NX_INSTALL" "$NX_DATA" | tee "$LAB/evidence/05-paths.txt"
cat "$NX_DATA/etc/nexus.properties" | tee "$LAB/evidence/06-listener-config.txt"

Prediction P-01: before the first run, the install tree exists but the full persistent work tree is not populated. After startup, logs/database/blob-related directories and files should appear under $NX_DATA.

4. First start and read-only evidence

Start $NX_INSTALL/bin/nexus run in Terminal A. In Terminal B:

LAB="$HOME/nexus-ch02-checkpoint"
cd "$LAB/instance"
NX_INSTALL="$(find "$PWD" -maxdepth 1 -type d -name 'nexus-*' -print -quit)"
NX_DATA="$PWD/sonatype-work/nexus3"
NX_URL=http://127.0.0.1:8081

until curl -fsS "$NX_URL/service/rest/v1/status" >/dev/null; do sleep 3; done
curl -sS -o /dev/null -w 'read=%{http_code} writable=' "$NX_URL/service/rest/v1/status"   | tee "$LAB/evidence/07-status.txt"
curl -sS -o /dev/null -w '%{http_code}\n' "$NX_URL/service/rest/v1/status/writable"   | tee -a "$LAB/evidence/07-status.txt"
ps -eo user,pid,ppid,args | grep '[n]exus' | tee "$LAB/evidence/08-process-before.txt"
ss -ltnp 2>/dev/null | grep ':8081' | tee "$LAB/evidence/09-listener.txt" || true
find "$NX_DATA" -maxdepth 2 -type d -printf '%P\n' 2>/dev/null | sort | tee "$LAB/evidence/10-data-map.txt"
du -sk "$NX_DATA" | tee "$LAB/evidence/11-data-size-before.txt"

Verify P-01: the data tree now exists, the listener is loopback, and the status endpoint is ready. In Settings → Support → System Information later, confirm Nexus version, Java runtime, install/work directories and host/port. Do not infer those values from a tutorial screenshot.

5. Bootstrap admin safely and create one disposable repository

Open http://127.0.0.1:8081/. Sign in as admin using the generated $NX_DATA/admin.password without printing or copying it into evidence. Complete Community onboarding, including the current CE EULA acceptance step, set a lab-only unique admin password, and disable anonymous access for this checkpoint.

Then go to Settings → Repository → Repositories → Create repository → raw (hosted). Create exactly:

Prediction P-02: bootstrap changes security metadata while artifact blob usage should not materially grow from package content because no package was uploaded. Prediction P-03: creating the empty hosted repository changes repository configuration metadata but creates no learner artifact asset.

Capture a repository-list screenshot or sanitized API/UI export without credentials, and record du -sk "$NX_DATA". Explain small background growth from logs/index/application activity rather than claiming “zero bytes changed.” The prediction concerns the absence of a learner artifact payload.

6. Record runtime/database/blob/edition evidence

Create evidence/12-system-summary.txt manually from System Information with: Nexus version/build, Community/edition state, Java vendor/version, install directory, work/data directory, application host/port, OS. Do not dump every environment variable.

# Sanitize a narrow log extract only.
grep -E 'Started|Java|H2|datastore|blob|Nexus Repository|ERROR|WARN' "$NX_DATA/log/nexus.log"   | tail -120   | sed -E 's/(password|token|secret|authorization)=[^ ]+/\1=[REDACTED]/Ig'   | tee "$LAB/evidence/13-log-extract.txt"

find "$NX_DATA" -maxdepth 2 -type f -printf '%P\t%s\n' 2>/dev/null   | sort | head -120 | tee "$LAB/evidence/14-state-files.txt"
du -sk "$NX_DATA" | tee "$LAB/evidence/15-data-size-after-config.txt"

The evidence should demonstrate H2/default local-state assumptions through current UI/log/runtime evidence, while avoiding unsupported direct database inspection. Do not open H2 files with another tool while Nexus is running and do not edit blob metadata.

7. Clean restart and persistence proof

Record the current PID. Stop foreground Nexus cleanly with Ctrl+C; wait for port 8081 to close. Start the same $NX_INSTALL/bin/nexus run again and wait for readiness.

curl -sS -o /dev/null -w 'after-restart=%{http_code}\n'   http://127.0.0.1:8081/service/rest/v1/status   | tee "$LAB/evidence/16-status-after-restart.txt"
ps -eo user,pid,ppid,args | grep '[n]exus' | tee "$LAB/evidence/17-process-after.txt"
ss -ltnp 2>/dev/null | grep ':8081' | tee "$LAB/evidence/18-listener-after.txt" || true

Sign in with the lab-only password you set—not the initial password—and confirm academy-ch02-persistence still exists. That verifies P-02/P-04: process identity/PID is transient; application configuration/security metadata persists in the data state. The empty repository still has no learner artifact payload.

8. Controlled diagnostic challenge

Without changing the server, request a misspelled path:

curl -sS -D "$LAB/evidence/19-broken-headers.txt"   -o "$LAB/evidence/19-broken-body.txt"   -w 'http=%{http_code}\n'   http://127.0.0.1:8081/repository/academy-ch02-persistance/example.txt   | tee "$LAB/evidence/19-broken-summary.txt"

Diagnose it in the required order: server readiness → URL/auth → repository name/type → authorization → component/asset state. The typo is persistance versus persistence. The correct action is to fix the client endpoint. Do not clear caches, delete the repository, edit the database, or touch blobs.

9. Evidence packet checklist

10. Safe cleanup and rollback

Cleanup is intentionally conservative. First stop Nexus and prove that the target is the exact disposable checkpoint directory. Preserve evidence/ elsewhere if you want it; otherwise remove the whole lab as one unit. Do not cherry-pick internal database/blob files for deletion.

# Nexus must already be stopped.
LAB="$HOME/nexus-ch02-checkpoint"
test -d "$LAB/instance" || { echo "Unexpected target" >&2; exit 1; }
test -f "$LAB/evidence/05-paths.txt" || { echo "Checkpoint marker missing" >&2; exit 1; }

# Verify no listener remains.
if ss -ltn 2>/dev/null | grep -q ':8081'; then
  echo "Port 8081 is still listening; investigate before cleanup" >&2
  exit 1
fi

# Optional: preserve evidence first.
# cp -a "$LAB/evidence" "$HOME/nexus-ch02-evidence-preserved"

printf 'About to remove only: %s\n' "$LAB"
# After visually confirming the exact disposable path:
rm -rf -- "$LAB"

Rollback note: before deletion, rollback is simply restart the known lab instance from its intact data tree. After deletion there is no rollback unless you preserved a backup; that is why the target proof happens first. This chapter intentionally does not teach “restore by copying internals.”

11. What Chapter 02 adds to the production operating model

You can now describe a Nexus platform before discussing individual package formats: exact release/runtime, edition, process identity, network connector, replaceable install tree, persistent data tree, database, blob storage, readiness, bootstrap security, resource limits, restart behavior and evidence. Those are the invariants an operator must preserve through deployment, upgrade and recovery.

Knowledge check

12. Summary

The checkpoint proved deployment causality: a pinned supported archive created a loopback service; first start created persistent H2/data/blob/log state outside the versioned application tree; bootstrap changed security metadata; repository configuration survived process restart; a routing typo was repaired at the client URL layer; and cleanup removed only the verified disposable instance.

Official references and version notes

• Download Nexus Repository — official current download page; at review time it presents 3.94.1 as the downloadable self-hosted release.
• Nexus Repository 3.95.0 release notes — official release notes state that 3.95.0 was released August 5, 2026; this is intentionally called out because the download/version indexes can lag.
• Nexus Repository system requirements — supported operating systems, dedicated-user guidance, file handles, Java 21, memory, H2 limits, and PostgreSQL requirements.
• Java Runtime Compatibility Matrix — Java 21 is the supported runtime for H2/PostgreSQL Nexus Repository 3.87.0 and later.
• Install Self-Hosted Nexus Repository — archive installation, default H2/local blob behavior, initial admin state, and deployment planning.
• Configuring the Runtime Environment — install-dir versus data-dir configuration, nexus.vmoptions, nexus.properties, port, context path, logs, and temporary state.
• Nexus Repository Database — embedded H2 versus external PostgreSQL usage boundaries.
• Install Nexus Repository with PostgreSQL — supported external PostgreSQL setup and Nexus datastore configuration.
• Self-Hosted Nexus Repository Feature Matrix — current Community Edition versus Professional capability boundaries.
• Community Edition Onboarding — current CE onboarding/EULA workflow and 40,000-component / 100,000-request-per-day usage limits.
• Usage Center — current Community Edition usage-limit behavior and operational monitoring.
• Status API — current readiness, writable-state, and authenticated status-check endpoints.
• System Information — read-only server evidence including version, install/work directories, host/port, JVM, OS, and runtime details.
• Run as a Service — dedicated process identity, service configuration, and supported runtime override mechanisms.

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.