Skip to main content

Upgrading a Standalone Instance

Upgrading Sonatype Nexus Repository presents a necessary step to gain access to new features, bug fixes, performance improvements and other advantages. Regular updates to the latest release are recommended as a general best practice. Version 3 upgrades will only work from version 3.0.0 milestone 7 and later.

Obtaining the New Version

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

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

    For example, using 3.23.0-03 version...

    tar xzvf nexus-<version-number>-mac.tgz
tar xzvf nexus-<version-number>-unix.tar.gz
7za.exe nexus-<version-number>-win64.zip

  3. Compare the nexus-<version-number>/bin/nexus.vmoptions file with your existing version.

Pre-Upgrade Checklist

Warning

Before proceeding, have you done the following things?

  • Review release notes to understand any important or breaking changes. If using Nexus Lifecycle features, ensure that your new version will be compatible.

  • Become familiar with the basic directory structure of a Sonatype Nexus Repository installation. You are encouraged to stick with the standard installation layout to make future upgrades as simple as possible.

  • Determine and record your existing installation data directory location for later use.

  • OrientDB deployments - Ensure you have adequate free space for the checkpointed databases before upgrade.

    • Databases will be checkpointed automatically to the data directory upgrades directory during upgrade.

    • Databases are compressed but still may consume disk space equivalent to the size of the database backups produced by the Admin - Export databases for backup task.

  • Content Replication Users - 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. Content replication will pick up from the last successful replication timestamp and begin replicating any changes since that stored timestamp.

    • If you do not pause replication, the instances will temporarily be on different versions; this will cause replication to fail as both instances must be using the same version. Once both instances are on the same version again, content replication will pick back up from the last successful replication timestamp, which is stored in the repository configuration. Content replication will then replicate an content added since that timestamp.

    • As a best practice, keep the time between upgrading each instance minimal. Otherwise, it may take a significant amount of time for content replication to catch up.

  • Upgrades from a version older than 3.26.0 - Is your jetty-https.xml file outside of the install directory? If so, you will need to make some changes to it as we updated the Jetty version in 3.26.0 and older jetty-https.xml files will not work.

    • Find the line below in your jetty-https.xml file:

      <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">

    • Add "$Server" so that it looks like the following:

      <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory$Server">

  • If you changed the default location of the data directory (sonatype-work by default), then edit ./bin/nexus.vmoptions and change the line -Dkaraf.data=../sonatype-work/nexus3 to point to your existing data directory.

    • Example: -Dkaraf.data=/app/nexus3/data

    • You will also need to change the location of these 4 values: -Dkaraf.data, -Djava.io.tmpdir, -Dkaraf.log and -XX:LogFile

  • If you changed the default location of the temporary directory, then edit ./bin/nexus.vmoptions and replace the line -Djava.io.tmpdir=../sonatype-work/nexus3/tmp to point to your preferred temporary directory.

  • If you adjusted the default Java virtual machine max heap memory, then edit ./bin/nexus.vmoptions and edit the line containing -Xmx accordingly.

  • If you have enabled jetty HTTPS access, make sure your etc/jetty/jetty-https.xml SSL keystore location is still available to the new install and configured according to our recommendations.

  • If you manually adjusted any other install files under ./etcyou will need to manually perform a diff between the old files and the new files and apply your changes if applicable to the new version.

Perform the Upgrade

  1. Ensure you have taken recent backups of the existing Data Directory and any custom blobstore locations according to our recommended practices. Because of involved Upgrade steps, downgrading a Nexus Repository version is not supported and will almost always result in failures. If you have issues, restore from this backup instead.

  2. Stop your existing install using the scripts under ./bin or your operating system service. Make sure it stops completely.

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

  4. Review the log files for any possible issues and sign-in to the server to confirm things are working as expected.

Note

If you are using an H2 or PostgreSQL database and upgrading from a pre-3.48.0 release to 3.48.0 or later, you will need to run a task to rebuild metadata for each existing Apt, Helm, and Yum repository after upgrading:

  • Apt - Rebuild Apt metadata for each Apt repository

  • Helm - Rebuild Helm metadata for each Helm repository

  • Repair - Rebuild Yum rebuild metadata (repodata) for each Yum repository