Upgrade Planning, Version Support, Breaking Changes, Java Runtime Upgrades, and Rollback Strategy: Concepts, Architecture, and Mental Model

1. The practical problem: “latest” is not an upgrade plan

The target version may be supported and still be unsafe for your exact instance. Your path depends on the source version, database engine, Java mode, blob backend, edition, plugins, repository formats, TLS customizations, and the thresholds crossed between source and target. The upgrade decision therefore starts with evidence, not with downloading a ZIP.

2. The upgrade state machine

flowchart TD
A[Inventory source] --> B[Read version status + release notes]
B --> C[Evaluate upgrade-path thresholds]
C --> D[Verify recovery checkpoint]
D --> E[Rehearse on cloned disposable state]
E --> F[Change window]
F --> G[Start target version]
G --> H[Run required migrations/rebuilds]
H --> I[Smoke + client + security validation]
I --> J{Accept?}
J -->|yes| K[Close rollback window deliberately]
J -->|no| L[Restore supported checkpoint]

The arrows matter: a successful process start is only one transition. Required rebuilds, client semantics, authorization, remote TLS, and repository behavior still have to pass.

3. Replaceable application versus persistent state

For an archive-style standalone install, the Nexus application directory is replaced by the new distribution; the persistent data directory remains the authoritative instance state. Custom JVM options, Jetty/TLS configuration, service wrappers, or files under the old application directory must be reviewed and deliberately re-applied to the new distribution where still supported. Never treat an old application directory as the backup of the database/blob state.

4. Three documents answer three different questions

Do not substitute one for the others.

5. Java 21 is a runtime gate and a trust-store gate

Current Nexus requires Java 21. Official installers/images bundle Java 21, so most modern upgrades do not require managing the system JVM. However, if you intentionally use an external JVM, verify the Java compatibility matrix and your override settings. Also note the 3.87+ bundled-runtime transition: certificates added to a previous JVM truststore are not automatically inherited. A proxy, LDAP, or SAML integration can therefore fail after an otherwise healthy upgrade.

6. Threshold actions are cumulative

If your source is old, evaluate every threshold crossed. Examples from the current upgrade-path table include the 3.85+ repository-search rebuild requirement and the 3.87+ bundled Java 21/truststore transition. A source far behind the target may cross several gates in one planned change.

{
  "source": "3.84.2",
  "target": "3.95.2-01",
  "crossedGates": [
    "3.85+: Repair - Rebuild repository search",
    "3.87+: bundled Java 21; re-check custom trust anchors"
  ]
}

7. Release-specific behavior belongs in acceptance tests

The 3.95.x notes, for example, call out search visibility that may require a rebuild for content-selector-only users and an Ansible duplicate-version response shift to HTTP 409. That means your acceptance plan should test the formats and privilege patterns you actually use rather than declaring victory from the login page.

8. Community plugins are an explicit risk

Sonatype does not support community plugins and warns that many do not work with recent versions or PostgreSQL mode. Inventory every extension before the window. The safe choices are: remove it, replace it with supported UI/REST functionality, prove compatibility in rehearsal, or delay the upgrade with an owned risk decision. Do not discover plugin incompatibility in production startup.

9. Rollback checkpoint

Before starting the target version, preserve a coherent recovery point: database/configuration, blob stores, node identity/secrets and custom configuration required by your deployment. Record the exact source Nexus and Java versions. If the target mutates schema/data, rollback is a restore operation against that checkpoint—not “put the old binaries back.”

10. Acceptance ladder

1. Target starts on intended Nexus/Java/database.
2. No unresolved migration/rebuild tasks.
3. Hosted assets resolve and sample hashes match preflight evidence.
4. Proxy/group routes and remote TLS work.
5. Least-privilege users retain intended permissions.
6. Representative Maven/npm/Docker/PyPI/NuGet clients used by the organization behave correctly.
7. Scheduled tasks/APIs/webhooks used operationally still function.
8. Logs show no unresolved upgrade errors.
9. Rollback checkpoint remains available until acceptance is signed off.

Knowledge check

Summary and next step

An upgrade is a version-constrained state transition governed by release evidence, threshold actions, runtime/storage compatibility, a verified recovery point, and behavioral acceptance tests.

Lesson 2 turns the model into a disposable rehearsal and runbook workflow.

Official references and version notes

• Sonatype: Upgrade Nexus Repository — standalone upgrade workflow, backups, install/data separation, vmoptions, TLS/custom configuration, and validation.
• Sonatype: Nexus Repository Upgrade Paths — version-crossing actions and compatibility gates.
• Sonatype: Nexus Repository 3 Versions Status — support status and community-plugin guidance.
• Sonatype: Nexus Repository 3.95.x Release Notes — current-line changes, known issues, and upgrade guidance.
• Sonatype: System Requirements — current Java 21 and operating requirements.
• Sonatype: Upgrade Nexus Repository Java Version — bundled Java behavior and external-JVM considerations.
• Sonatype: Java Runtime Compatibility Matrix — release-specific external Java compatibility.
• Sonatype: Prepare a Backup — coherent database/blob/configuration recovery preparation.
• Sonatype: Upgrading to 3.71.0 and Beyond — legacy OrientDB/H2 gates.
• Sonatype: Rolling Upgrades in High Availability — Pro/HA mixed-version and finalize-upgrade semantics.