Upgrade from Nexus Repository 2
Nexus Repository 3 is a complete redesign that does not include legacy code from Nexus Repository 2. Nexus Repository 3 uses a different storage model for managing components that is far more scalable for non-Maven ecosystems and deployment environments. While this avoids file system limitations from Nexus Repository 2, upgrading 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.
Review the Feature Equivalency Matrix
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.
Upgrade to Nexus Repository 2.15.2 and Nexus Repository 3.76.0
Community Edition (CE): both instances must be on corresponding versions of Nexus Repository 2 and 3. Nexus Repository 3 CE deployments need to migrate to 3.76.0 deployed with Java 17 using an H2 database before upgrading to later versions.
Professional (Pro) License: Upgrade to the latest version with an external PostgreSQL database.
For upgrading to a fresh Nexus Repository 3 instance
This method is not supported when already using Nexus Repository 3.
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.
See Upgrade Wizard
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.
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 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.
Using the Repository Import Task
Organizations may consolidate by importing 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.
Directly import Nexus Repository 2 repository content
The import task brings in the content of a folder on disk that the server has permissions and access to.
The repositories from Nexus Repository 2 are already in this format and do not need to export them from the repository first. You may connect directly to the repository on disk or using a backup. Using Hard Linking is far faster and does not duplicate the data on disk.
New files added after the import start are picked up by the task and imported. The import may be run multiple times to bring in any differences.
Repository configuration is 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. The import task is able to maintain the created date, last updated date, and the last downloaded date attributes from Nexus Repository 2.
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.
Repositories are imported one a a time.
You need to create and run individual tasks for each repository. Multiple tasks do not run at the same time.
Importing is not as fast as using the Upgrade Wizard
This method takes significant amount of time when importing a lot of data to copy into the repository. Use the Proxying Repositories method below to make the source content available while waiting for the import tasks to complete.
Steps for the Import Upgrade
Nexus Repository 3 must have file system access to the Nexus Repository 2 storage. Use a backup when Nexus Repository 2 is located on a different server.
Create a repository to import content.
Create a new import task. Set the source directory to the folder where the Nexus Repository 2 repository is stored. Select
Enable Hard Linkswhen available.Run the task.
Repeat these steps for each repository to import.
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.
Proxying Repositories Manual Upgrade Method
One common use case for proxy repositories is to use them to make content immediately available on a new Nexus Repository instance while slowly moving content as it is requested.
Considerations
This upgrade will only copy content that is actively being requested by development and production. This may be an effective way to avoid moving unused content.
Nexus Repository fetches imported components through the proxy over HTTP(S), which can be very slow.
You will need to maintain both repository instances until your new instance contains all needed content.
You cannot convert a proxy repository to a hosted repository when the process is complete.
Steps for the Proxying Repositories Manual Upgrade Method
This method involves creating a proxy repository (called target-proxy in the example below) on the new Nexus Repository 3 instance and having that proxy repository use the URL of hosted repository on a source instance (called source-hosted in the example below).
When a component is requested from but not found on the target repository group (called request-endpoint in the example below), Nexus Repository downloads the component from the hosted repository on the source instance through the proxy repository. This is demonstrated in the diagram below:
 |
This configuration can be used until the upgrade is complete.