How to Upgrade to Nexus Repository Manager 3.0.x

NOTE: This is an older article. Current upgrade instructions can be found here.

Before Upgrading

If you are running any version of Nexus Repository Manager 2 you must first upgrade to the latest 2.x version after 2.14.1. Upgrading from any earlier 2.x version will not work and is not supported. Our book has specific 2.x and 3.x version compatibility and procedures.

If you are running Nexus Repository Manager 3.0.0-m7 please upgrade to 3.0.0 final first, before upgrading to a later version. Upgrading from earlier 3 milestone releases is not supported or tested.

If you are running Nexus Repository Manager 3.0.0 or 3.0.1 and upgrading to 3.0.1 or 3.0.2 then follow the upgrade instructions in this article. In order to keep your upgrade as simple as possible, schedule Nexus downtime during the upgrade so that you can stop Nexus and backup important directories during the upgrade process.

The examples below use version 3.0.1-01 as the version you are upgrading to - replace this with your version.

If you are running Nexus Repository Manager 3.0.x and upgrading to 3.1.x then there are specific instructions to follow for upgrade to be aware of as the directory structure has changed in 3.1.0 and later.

If you are running Nexus Repository Manager 3.1.0 and newer then consult our general instructions. You can learn more about upgrade expectations and procedures in the Nexus Repository Manager book.

WARNING: The upgrade tool is specifically designed to help you upgrade data and configurations from the Nexus Repository Manager 2 to 3. Therefore, we discourage running data center to data center transfers while simultaneously upgrading the source repository manager (version 2) to the target (version 3).

In more detail, the scenario of moving on-premises data center files to a cloud server (or vice-versa) while upgrading will make it difficult to single out and diagnose performance issues related to the repository manager, if they occur. Instead, manage your data center file transfers separately from planning (and executing) your upgrade, or the other way around.

Upgrade Using the Installer Archive

The archive distribution offers the familiar process of downloading and simply extracting the archive in place - there is no graphical or automated process.

You will have to determine your previous installation data directory location. Record this value for later use.

Extract the distribution archive.

tar xzvf nexus-installer-3.0.1-01-mac-archive.tgz
tar xzvf nexus-installer-3.0.1-01-unix-archive.tar.gz
7za.exe nexus-installer-3.0.1-01-win64-archive.zip

Edit the nexus-3.0.1-01/bin/nexus.vmoptions file.

• replace the line -Dkaraf.data=data to point to your previous data directory
  Example: -Dkaraf.data=/app/nexus3/data

Make sure the old Nexus 3 installation is not running.

Manually backup the contents of the previous Data Directory to another location.

Inside your previous Data Directory, manually create an empty file named clean_cache
Example: /app/nexus3/data/clean_cache

Manually review installed files and merge in any of your custom changes.

Start the new installation using the scripts under nexus-3.0.1-01/bin/ or your operating system service.

Sign-in to the Nexus user interface and check the log file if you notice a problem.

Manually Reviewing Customized Files Is Required

There are some special files that the installer will not upgrade automatically. Instead it simply installs the default copy of these.

We recommend comparing the contents of the new files to your previous copy, and then manually merge in any custom changes you have made. Do not just use your old version or new version without doing a comparison as you could miss an important change to these files that should apply to the new version.

Commonly edited file patterns that require manual review include:

• bin/nexus*
• etc/org.sonatype.nexus.cfg
• etc/jetty*.xml
• etc/*.properties

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

If you have customized the temporary directory used by Nexus ( java.io.tmpdir ), then ensure you update your bin/nexus.vmoptions file to reflect the custom location.

Ensure any operating system service scripts you might have copied from old versions are updated to reference the newly installed version.

Upgrade Using an Installer Executable

You will have to determine your previous installation data directory location. Record this value for later use.

Always stop Nexus first before upgrading, so that backups of the data directory can be made by you during the upgrade process.

Start the installer. If installing with the same user account, the installer should automatically detect the previous Nexus 3 install and ask if you would like to upgrade the previous installation.

Select No, install into a different directory.

Click Next > until you reach the screen which prompts for the Nexus Destination Directory. Enter the path to a directory where the Nexus application runtime files should reside. A good option is to choose a Destination Directory location next to the previous Nexus 3 installation.

For example if you already have installed repository manager at /app/nexus3/nexus-3.0.0-03 then a good new destination if upgrading to 3.0.1-01 would be /app/nexus3/nexus-3.0.1-01 .

Click Next > until you reach the screen which prompts for the Nexus Data Directory location. Enter the path to your existing Nexus 3 Data Directory. The default value displayed will be the automatically detected data directory.

At this point:

• make sure the previous installation is not running and stop it if it is
• manually backup the contents of the data directory to another location

Continue to the Nexus Options screen. Select the Service tab and uncheck the option to automatically start the service.

Continue to the end of the installer steps by clicking Next > .

The installer will prompt you before it overwrites any files. Choose Yes or Yes to all to overwrite existing files.

Only in an exceptional case of where you may have manually modified a file inside the data directory might it make sense to not override a file. In this case, make note of the file path, and choose to overwrite the file anyways.

Manually review installed files and merge in any of your custom changes.

When you are satisfied the new installation is configured correctly, start it using your normal procedure. 

Sign-in to the Nexus user interface and check the log file if you notice a problem.