Skip to main content

Upgrade Nexus Repository

Upgrading the self-hosted Nexus Repository is necessary for new features, bug fixes, performance improvements, and other security patches. Regularly updating to the latest release is recommended.

Note

Upgrading beyond Nexus Repository 3.70.x brings key architectural changes for continued support and stability:

  • OrientDB End-of-Life: Versions past 3.70.x no longer support OrientDB as the embedded database. You must migrate your data to either H2 or PostgreSQL before upgrading to version 3.71.0 or later.

  • H2 Database Upgrade: The internal H2 database was upgraded to a newer major version which requires the data to be exported and reimported into the newer version.

  • Java Version: Nexus Repository 3.87.0+ includes a bundled Java 21 runtime. You normally do not need to upgrade system Java unless Nexus is configured to use an external JVM (`APP_JAVA_HOME` / `INSTALL4J_JAVA_HOME_OVERRIDE`) or you depend on system JVM customizations.

See Upgrading to Nexus Repository 3.87.0

Pre-Upgrade Checklist

  1. Review the Release Notes

    The release notes list compatibility or breaking changes. Changes to the architecture of Nexus Repository require users to review the new required configuration.

    See Nexus Repository Release Notes

  2. Download the Latest Binary

    Download the latest installer archive for your platform from the Downloads page.

    Extract the newest downloaded distribution archive using the standard approach. Archive distribution offers the familiar process of downloading and simply extracting the installation archive. There is no graphical or automated process and all commands are done inside a terminal console.

  3. Content Replication

    Pause content replication on the target instance while performing the upgrade to allow for a clean, predictable timeline for when replication is down. Re-start replication once you've upgraded both instances to the same version.

  4. Compare the nexus.vmoptions File

    Compare the bin/nexus.vmoptions file with your existing version. This file contains settings such as the temp file location and JVM memory setting.

    See Configuring the Runtime Environment

  5. Jetty HTTPS Access

    Check that the etc/jetty/jetty-https.xml SSL keystore location is available for the new installation and configured according to our recommendations.

  6. Review Custom Configuration

    If you manually adjusted any other install files under ./etc you need to perform a different comparison between the old files and the new files and apply your changes when applicable to the new version.

Note

Nexus Repository 3.87.x and later use a bundled Java 21 runtime. The default Java truststore from previous installations is not reused. If you rely on certificates added to the previous Java truststore (for example, for proxy repositories, LDAP, or SAML), those certificates must be reconfigured or made available to the new runtime.

Perform the Upgrade

  1. Backup the Nexus Repository

    Before performing the upgrade, it is mandatory to take a PostgreSQL database backup or ensure that PITR is configured and verified as they are used during the upgrade. The data directory is updated with changes needed to the configuration and indexing. Downgrading a Nexus Repository version is not supported and results in failure as you must restore the instance from a backup.

    See Prepare a Backup

  2. Review the Pre-Upgrade Checklist

    Ideally, configuration is maintained in the external database and the data directory

  3. Stop Nexus Repository

    Stop your existing instance using your operating system service. Wait for it to stop completely.

  4. Update your Service Scripts

    Start the new installation using the scripts under ./bin or adjust your operating system service to use these scripts.

    See Run as a Service

  5. Restart Nexus Repository

    Review the log files for issues and sign in to confirm Nexus Repository is working as expected.

Post Upgrade Validation

Validating your self-hosted Nexus Repository upgrade is crucial for maintaining your development pipeline. We recommend automating these steps using a test CI build that performs each of the following steps.

  1. Verify repositories are online and accessible

    1. Log in to the Nexus Repository UI as an Administrator.

    2. Navigate to Administration → Repository → Repositories.

    3. Examine the Status column to confirm that the status for repositories display Online.

      Other status may indicates an issue relating to storage mounting or configuration errors.

  2. Confirm uploads and downloads successful

    1. Testing Uploads: Test new uploads to hosted repositories using the UI upload and through client tools that publish artifacts. Uploads return an HTTP 200/201 status code when successful. Verify that the new artifact are found in the repository when browsing in the UI.

    2. Testing Downloads: Attempt to download the hosted artifacts through the UI using client tools by running a build pointing at both the hosted repository and the repository group where the hosted repository is found. Test requesting new artifacts through proxy repositories. Verify that the component was download from Nexus Repository and that the new component is found in the UI.

    3. Testing the Artifact: For critical artifacts, compare the file size or checksum (SHA1/SHA256) against pre-upgrade values to confirm data integrity.

  3. Test that users and service accounts authenticate

    1. Confirm your primary administrator account (and any necessary backup accounts) can log in successfully via the UI.

    2. When using external security realms, attempt to log in with a non-administrator user whose credentials are managed by the external system. This validates the migration of the security realm configuration. Confirm that the user has the correct access to repositories they are authorized to access.

    3. Test that service accounts may perform the tasks required during their build.

  4. Review logs for errors or warnings post-startup

    1. Access the Nexus Repository logs in the data directory.

      $NEXUS_DATA/log/nexus.log

    2. Review the messages immediately following the successful service start represented by the first few thousand lines of activity.

    3. Review the logs for messages including the terms FATAL, ERROR, or WARN that directly relate to data store corruption, migration failures, or critical service components failing to start.

    4. Look for messages indicating a successful startup including: "Started Jetty Server" and "Started Sonatype Nexus Repository."

  5. Confirm blobstore verify without discrepancies

    1. Log in to the UI as an administrator and navigate to Administration → System → Blob Stores.

    2. Confirm that every listed blob store has a State equal to Started. Other states indicating a problem with mounting or accessing the storage volume.

    3. Navigate to Administration → System → Tasks and run the "Verify blob store integrity" task against production blob stores. The task summary and logs should explicitly show that the check passed without discrepancies, meaning every artifact file on disk is properly tracked by the Nexus Repository database.