Skip to main content

Determining and Planning Your Upgrade Path

Upgrading from Nexus Repository 2 to 3 requires completely transforming the repository metadata and artifact storage model.

You need to use one of the following upgrade methods:

Method

Requirements and Limitations

Built-in Upgrade Wizard

(Preferred)

  • For upgrading to a fresh Nexus Repository 3 instance. This method is not supported when you are already using Nexus Repository 3.

  • Both instances must be on the latest versions of Nexus Repository 2 and 3 before upgrading

  • Use the same license type (Community or Pro) after upgrading. You cannot upgrade when one instance has the Professional license and the other is the Community edition.

  • All files in the work directory must be owned by the OS user and there are no zero-length files.

    Review the Upgrade Prerequisites for details.

  • The Nexus Repository 2 repository and repository groups must use distinguishable names.

    Nexus Repository 2 allows different cases for repository names however Nexus Repository 3 requires the names to be unique.

Exporting / Importing Content

(Preferred)

  • Best for those already using Nexus Repository 3 and wishing to bring Nexus Repository 2 content into the existing Nexus Repository 3 instance

  • Content cannot be imported into a proxy repository. The proxies from Nexus Repository 2 would need to be imported as hosted repositories.

  • The export/import only moves repository contents, not the repository configuration. Metadata such as creation and last download dates are set to when the content is imported into Nexus Repository 3.

  • This method may lead to a potentially lengthy upgrade process while doubling the required storage.

  • Content does not have to be exported from Nexus Repository 2. Nexus Repository 3 may point directly to the repositories as stored on disk to import.

Proxy Repositories

  • This method is best when only required to bring over what is actively being used/requested from Nexus Repository 2.

  • This method is not appropriate when you cannot maintain or are required to shut down your Nexus Repository 2 instance and storage.

  • This method may become a prolonged upgrade process allowing time for artifacts to be requested and proxied.

  • You must allow inbound network traffic from Nexus Repository 3 to Nexus Repository 2 instance.

  • This method will only move repository contents and not configuration.

Hybrid Model

  • Only consider the hybrid model when you have access to Sonatype Support and Customer Success teams due to the complications with this method.

  • A common hybrid scenario would use the Upgrade Wizard to move user tokens and some configuration, and then use manual methods for moving content and building out the rest of the configuration.

Upgrading while in a Highly Available (HA) Nexus Repository 3 Architecture is Not Supported

Using the upgrade wizard when Nexus Repository 3 instance is configured as a multi-node highly available resilient deployment is not supported. We require first upgrading to a Nexus Repository 3 instance using a single node deployment before upgrading to the resilient architecture.

The upgrade wizard was not designed to support highly available deployments.

Storage Planning for the Nexus Repository 3 Upgrade

Whether using the Upgrade Wizard or Import method, we always recommend using hard links when possible. Using hard linking saves time and storage space.

See hard linking requirements when using the Upgrade Wizard or hard linking requirements when using the import task.

When Planning to Use Cloud Object Storage

Moving to cloud object stores (e.g., S3 blob stores) takes two to three times longer than moving to other storage options.

We recommend importing to a file-based blob store on a low-latency file system and following the instructions in Moving a Blob Store to move the content to the cloud object store.

Nexus Repository 2 APIs and Plugins

Custom plugins and scripts written using the Nexus Repository 2 APIs are not compatible and do not work for Nexus Repository 3. Scripts and plugins will need to be rewritten using the Nexus Repository 3 API.

Nexus Repository 3 will support legacy Nexus Repository content URLs for fetching components; however, you should transition builds to Nexus Repository 3 URLs when possible.

When Using the IQ Server

The Upgrade Wizard clones the IQ Server configuration and expects that Nexus Repository 3 uses the same server. The data inside the IQ Server for Nexus Repository 2 is cloned to work with the repositories upgraded to Nexus Repository 3.

When Using the Repository Firewall Solution

The Upgrade Wizard will move Repository Firewall waivers and approved components to your new Nexus Repository 3 instance.

While you cannot manually move Firewall waivers and approval, you can pre-fetch approved (waived) components before enabling Firewall quarantine on the new repository.

  1. Export the Firewall report from the source repository using the IQ Server REST API for Repository Results.

  2. Use this report to request components from the new proxy repository.

  3. Enable Firewall quarantine on the new repository once all of the allowed components have been proxied.

RPMs in Maven Repositories

Nexus Repository 2 supported storing RPMs in Maven repositories as a stopgap for the lack of native RPM support. Nexus Repository 3 natively supports RPM repositories; however, moving these artifacts to a native RPM repository is not supported using the upgrade wizard. We highly suggest using the import task to move these into Yum-hosted repositories in Nexus Repository 3.

Disable the Yum: Configuration capability on Maven repositories in Nexus Repository 2 or the hosted repositories with this configuration will not be imported using the upgrade wizard.