Determine Your Upgrade Path
Upgrading from Nexus Repository 2 to 3 requires completely transforming the repository metadata and artifact storage model.
Nexus Repository 3 has a non-destructive built-in upgrade wizard to migrate content from Nexus Repository 2 deployments. While this method is recommended and acceptable for most deployments some caveats must be considered before beginning.
Built-in Upgrade Wizard
Using the upgrade wizard is the preferred method when your deployment meets all of the requirements. In some cases, you may combine this method for the majority of the migration along with other methods for content that falls out of the requirements.
For upgrading to a fresh Nexus Repository 3 instance This method is not supported when already using Nexus Repository 3.
Upgrade to the latest release Both instances must be on the latest versions of Nexus Repository 2 and 3. Nexus Repository 3 OSS deployments need to migrate to 3.76.0 before upgrading to later versions.
Use your Pro license for both deployments You cannot upgrade when only one instance has the Pro license installed.
Repositories must use unique names Nexus Repository 2 allowed different cases for repository names. This is not allowed in Nexus Repository 3.
Exporting / Importing Content
Organizations using both versions of Nexus Repository and needing to consolidate must import the content into Nexus Repository 3 using the Repository Import task.
Already using Nexus Repository 3 Best for those already using Nexus Repository 3 and needing to import Nexus Repository 2 content into the existing Nexus Repository 3 instance.
Configuration and component metadata are not migrated This moves repository contents, not the configuration. Metadata such as creation and last download dates are set to when the content is imported into Nexus Repository 3.
This may complicate cleaning up repositories after importing.
Cannot import to proxy repositories Proxy repositories from Nexus Repository 2 would need to be imported as hosted repositories.
Importing through Proxy Repositories
Using proxy repositories is an effective way of making Nexus Repository 2 content available in Nexus Repository 3 while both versions are used in production.
Migrate content in active use Only the content actively requested in Nexus Repository 3 is fetched from Nexus Repository 2. This may be a method to separate unused content.
Must maintain Nexus Repository 2 The Nexus Repository 2 must be available for Nexus Repository 3 to fetch content so both environments would need to be maintained for a long enough amount of time for all content to be migrated. This method may be difficult to know when Nexus Repository 2 is no longer needed.
Self-hosted content is in proxy repositories The content from Nexus Repository 2 is stored in proxy repositories in Nexus Repository 3.
Requires substantial configuration This method requires creating a proxy repository for every repository to migrate from Nexus Repository 2. We recommend adding these proxies to group repositories so that hosted content is accessible by a single endpoint.
Upgrading Considerations
Highly Available Architecture is Not Supported The upgrade wizard was not designed for and does not support upgrading with Nexus Repository 3 configured for a multi-node highly available deployment.
Upgrade with Nexus Repository 3 as a single node deployment before upgrading to the resilient architecture.
Hard Linking Hard Linking does not require the file system to copy components as it updates the file pointer to the content stored on the disk. While limited to in-place upgrades, this method greatly shortens the time and storage required to run the upgrade.
We highly recommend using Hard Linking when possible.
See Hard Linking
Cloud Object Storage Migrating to Cloud Storage takes 3 times longer than moving to storage on a file system. We recommend importing to a file-based blob store on a low-latency file system before migrating content to a cloud object store.
Nexus Repository 2 API and Plugins Scripts written using the Nexus Repository 2 APIs are not compatible and do not work for Nexus Repository 3. Plugins need to be rewritten using the Nexus Repository 3 API.
IQ Server Configuration The upgrade wizard clones the IQ Server configuration and data to work with the repositories upgraded to Nexus Repository 3.
Repository Firewall Quarantined Component The upgrade wizard transfers approved and quarantined components to the Nexus Repository 3 instance. For manual migrations, pre-fetch approved components before enabling Firewall quarantine on the new repository. Use the Repository Results REST API to export the audit report from the source repository to request the same components from the proxy in Nexus Repository 3. Enable Repository Firewall quarantine on the repository once the allowed components are proxied.
RPMs in Maven Repositories Storing RPMs in Maven repositories was a stopgap in Nexus Repository 2. Nexus Repository 3 natively supports RPM in their own repository format. The upgrade wizard is unable to separate RPMs from Maven repositories with this configuration. Migrating Maven repositories with this configuration set is disabled by default.
We recommend using the import task to move RPMs into Yum-hosted repositories in Nexus Repository 3. You must disable the Yum configuration capability on Maven repositories in Nexus Repository 2 to include these repositories in the migration wizard.