Nexus Repository Editions, Deployment Models, Architecture, Installation, and Java Runtime Planning: Diagnostics, Failure Modes, Security, and Performance

1. The diagnostic sequence

flowchart TD
E[Preserve concise evidence] --> V[Version edition runtime]
V --> C[Client URL and auth]
C --> R[Repository type routing group]
R --> A[Authorization]
A --> M[Component asset metadata]
M --> P[Proxy cache upstream]
P --> S[Database blob disk]
S --> L[Logs tasks metrics]
L --> F[Least destructive correction]
F --> Q[Controlled verification request]

This order prevents “fixes” from destroying the evidence that identifies the layer. A 401 is not a reason to rebuild metadata. A 404 caused by a misspelled repository is not a reason to clear blobs. A startup failure caused by Java compatibility is not a reason to delete the database. Preserve the first failure and narrow the causal layer.

2. Unsupported Java and unsafe process identity

Current H2/PostgreSQL Nexus 3.87+ requires Java 21. If an operator overrides the bundled runtime with Java 17 or Java 25, treat the runtime mismatch as the primary suspect. Capture the Nexus version, configured APP_JAVA_HOME/app_java_home, Java version, and startup log before changing anything.

# Read-only evidence examples
ps -eo user,pid,args | grep '[n]exus' || true
grep -E 'java|JVM|version|UnsupportedClassVersion|Started|ERROR' "$NX_DATA/log/nexus.log" | tail -120
ulimit -n

If the process owner is root, correct the service design instead of accepting “it works.” Sonatype explicitly says not to run Nexus as root and recommends a dedicated OS account. Stop the disposable instance, correct ownership/service identity, and start again. Do not recursively chmod world-writable as a shortcut.

3. File descriptors, disk, memory and IO

File-descriptor exhaustion can produce seemingly unrelated repository and network errors. Sonatype warns that running out of file descriptors can cause data loss. Record the process limit and open-file pressure; increase the dedicated service user's limit through the operating system/service configuration, then restart in a controlled window.

Disk pressure must be decomposed by path. Application binaries, data/log/temp, database state, and blob stores can grow differently. Deleting files under db or blobs to make df green is not troubleshooting—it risks corruption. Use Nexus cleanup/storage mechanisms and a capacity plan later in the course.

Memory diagnosis must distinguish JVM heap from direct/native memory and OS cache. Increasing -Xmx blindly can starve the operating system and make IO worse. Record heap/direct-memory configuration, host RAM, GC/runtime symptoms and workload before tuning.

4. Install directory and data directory failure patterns

5. Intentionally broken example: accidental network exposure

Use only the disposable Chapter 02 instance. First preserve the healthy loopback listener. Then intentionally change application-host to 0.0.0.0, restart, observe the listener, and repair it. Do this only on a host whose firewall/private environment prevents external access during the brief experiment. If that condition is not true, use the supplied observation as a simulation and do not create exposure.

# BEFORE: preserve healthy config and listener.
cp "$NX_DATA/etc/nexus.properties" "$HOME/nexus-ch02-lab/evidence/20-nexus-properties-before.txt"
ss -ltn 2>/dev/null | grep ':8081' | tee "$HOME/nexus-ch02-lab/evidence/21-listener-before.txt" || true

# SECURITY-SENSITIVE / DISPOSABLE ONLY:
# Stop Nexus first. Then edit only this known lab property:
# application-host=0.0.0.0
# Restart and inspect; do NOT leave the instance this way.

ss -ltn 2>/dev/null | grep ':8081' | tee "$HOME/nexus-ch02-lab/evidence/22-listener-broken.txt" || true

# Repair: stop Nexus, restore loopback, then restart.
sed -i 's/^application-host=.*/application-host=127.0.0.1/' "$NX_DATA/etc/nexus.properties"
grep '^application-host=' "$NX_DATA/etc/nexus.properties"

Interpretation: the application itself may still return HTTP 200, so application readiness alone does not detect an over-broad network bind. The listener evidence proves the exposure layer. The repair changes only the connector binding; no repository, cache, database or blob deletion is warranted.

6. Initial admin endpoint on an untrusted network

Bootstrap is unusually sensitive because the generated initial admin password exists in the data directory and the account has broad authority. If you discover a fresh instance listening publicly, preserve minimal listener/version evidence, block exposure at the network/listener layer, rotate/bootstrap credentials in a trusted path, and review logs/audit evidence. Do not continue onboarding over an untrusted public HTTP connection.

7. Operations that deserve a change record

Credential/token changes, realms, roles/content selectors, TLS/reverse proxy, remote-repository credentials, cleanup policies, scheduled tasks, migration/upgrade mode, backups, database/blob configuration and public exposure all cross trust or persistence boundaries. For each: record before state, exact scope, rollback/restore point, expected state change, operator identity, and post-change verification.

8. Performance: identify the waiting layer

9. Controlled verification after correction

curl -sS -o /dev/null -w 'read=%{http_code}\n'   http://127.0.0.1:8081/service/rest/v1/status
curl -sS -o /dev/null -w 'writable=%{http_code}\n'   http://127.0.0.1:8081/service/rest/v1/status/writable
ss -ltn 2>/dev/null | grep ':8081' || true

Expected result: 200 readiness codes and a loopback-only listener. Then verify the original client action that failed. A diagnostic is complete only when the controlled request succeeds and the corrected state matches the intended security/architecture boundary.

Knowledge check

10. Summary

Reliable Nexus troubleshooting is a layer-by-layer investigation. Preserve the first failure, identify version/runtime/client/routing/auth/metadata/cache/storage/log evidence, correct the smallest causal state, and prove the original request plus the intended security boundary afterward.

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.