Upgrade Wizard Instructions
The upgrade wizard is meant to be used only once. Do not attempt to run the upgrade multiple times on production environments.
Test the upgrade in a testing environment We recommend attempting the upgrade in a test environment before the production deployment. Legacy environments are prone to accumulate missing records and errors over time. This helps identify and address any issues before impacting your production environment.
Upgrade Nexus Repository 2 to the latest version We strongly recommend that both instances are on the latest versions to have the most up-to-date improvements to the upgrade.
Configure the instance of Nexus Repository 3 The Nexus Repository 3 must be a new instance that has not been used in production. The upgrade process is destructive to most of the configuration in Nexus Repository 3 with the exception to the blob store configuration.
The Nexus Repository 3 instance is no usable during the upgrade, however the Nexus Repository 2 instance remains available.
Configure the storage for Nexus Repository 3 High available deployment models recommend relocated storage outside of the default instance configuration. We recommend setting this configuration before upgrading to reduce downtime later on.
See the Storage Guide for configuring blob stores.
Use the same license type in both instances When using a Professional license in Nexus Repository 2, you must use the same license in Nexus Repository 3. This unlocks many enterprise features that are not available in the Community Edition.
Overview of the Upgrade
The following are an overview of the upgrade process from Nexus Repository 2 to Nexus Repository 3.
Set the Upgrade Capability To secure access to the upgrade process, both instances must have the upgrade capability configured. An access token is set in Nexus Repository 2 to use when configuring the upgrade in Nexus Repository 3.
Configure the Connection Between Instances The
Upgradeview is available after the upgrade capability is set. This points Nexus Repository 3 to the Nexus Repository 2 instance to upgrade.Select the Content to Transfer Select the Content to Transfer
Select the Repositories to Transfer Select the Repositories to Transfer
Run the Upgrade Run the Upgrade
Finalize the Upgrade Finalize the Upgrade
Before you can use the Upgrade Wizard, you will need to configure upgrade capabilities on both the Nexus Repository 2 and 3 instances.
Nexus Repository 2 - Upgrade Agent Capability
Under to Administration → Capabilities, select New under the Capabilities tab.
Select Upgrade Agent as the capability type and the Enabled checkbox.
Use the generated Access Token or provide your own. Retain this token to use when performing the upgrade.
Select Add
Nexus Repository 3 - Upgrade Capability
Under Administration → Capabilities, Create an
Upgradecapability.Select the
Enable this capabilitycheckbox andCreatecapability.
In your Nexus Repository 3 instance, select the Upgrade view from the side menu. This launches the Upgrade wizard and takes you to the Overview view.
Read this information before proceeding.
Select Next to navigate to the Agent Connection view.
Enter the base URL for the Nexus Repository 2 instance. This URL must be discoverable and relative to the Nexus Repository 3 instance.
Nexus Repository 2 ships with a
/nexusweb context that must be included in the URL.Enter the Access Token when configuring the Upgrade Agent Capability in Nexus Repository 2.
The token is available in Nexus Repository 2 on the Upgrade Agent → Status tab.
Set the fetch size as the number of components requested at one time.
Setting the fetch size too high may cause out of memory errors in Nexus Repository 2. Consider reducing your fetch size to a smaller value from the default 100 components when the load on the server is of concern.
Select Next to continue.
 |
Select the content to transfer from your Nexus Repository 2 instance. Select both the repository content and server configuration unless directed by Sonatype Support. The server configuration checkbox is required.
 |
1. On the Repository Defaults screen, configure the default settings to use for your upgrade:
Blob store - Choose the blob store where the repository content should be stored.
Method - Choose how the repository content should be transferred (See Deciding on a Data Transfer Method).
Hard Link (fastest) (Recommended)
Filesystem copy (slow)
Download (slowest)
If your Nexus Repository 2 and 3 instances are running on different machines and do not share access to the same file system storage, you must use the HTTP download method.
 |
2. Select Next to continue to select the repositories you wish to upgrade.
3. On the Repositories screen, select the repositories you wish to upgrade by selecting the checkbox next to each repository; or, select the checkbox in the header row to select all repositories.
Repositories that you cannot upgrade to Nexus Repository 3 will appear greyed out and will not be selectable in the list.
 |
4. You can also select the wrench icon in the last column to customize the advanced configuration of the upgrade per repository as needed (e.g., to select a different blob store).
5. Review the preview of the upgrade configuration. These are all the steps that will take place during the upgrade after you select the Begin button at the bottom of the screen.
 |
The upgrade is broken into three phases:
Prepare - Prepares the transfer and creation of all configurations and components.
Sync - Counts and processes all components set to upgrade and upgrades all other configurations.
Finish - Performs the final clean up then closes the process.
1. To begin the upgrade from the Preview screen, select Begin; then, select Yes when asked if you wish to proceed. This will initiate the Prepare phase and take you to a progress screen where you can watch the progress of this phase.
The invoked upgrade process destroys any existing configuration in the target Nexus Repository 3 server and replaces it with the configuration from the Nexus Repository 2 instance.
From this point on, do not make further configuration changes in Nexus Repository 2. Any changes made will not be moved to Nexus Repository 3.
Note that the progress percentage above the table represents the number of completed steps in the phase (e.g., it may read 54% when 14 of 26 steps are complete).
2. When all steps in the Preparing phase are complete, select Continue to move to the Synchronizing phase.
3. Monitor the Synchronizing phase screen to observe progress; you can select the arrows in the first column to see more details. Any content changes to the version 2 repositories continue to be upgraded during the Synchronizing step (e.g., new proxied components or new deployed components in version 2 are transferred to version 3).
 |
During the transfer process, you can already view and access your content in Nexus Repository 3 by using the component search or browsing in repositories or repository groups. However, the repositories will be offline until the process is fully complete.
Nexus Repository 3 continues to ask Nexus Repository 2 for new content.
1. Once the Process changes step shows a sufficient amount of time "since last change," press Continue and then Yes when prompted to finalize the upgrade and move to the Finishing screen. Note that any future changes in Nexus Repository 2 will not be synchronized.
 |
2. Select Done on the Finishing screen to complete.
Repository content is available immediately for direct download.
Repair - Rebuild repository browse and Repair - Rebuild repository searchtasks run automatically after an upgrade completes to build component Search UI and Search REST APIs as well as component Browse UI and HTML views. You do not need to manually schedule tasks to rebuild search indexes or browse nodes.
Components will not be visible in the user interface (browse or search), HTML views of content, or Search REST API results until tasks named "Repo 2 Migration" finish. You can monitor this status in the Tasks section or by examining the associated task log.
Licensing Note
When you upgrade your versions on the same server, no additional work needs to be done. If you upgraded your Nexus Repository 3 to a different server than Nexus Repository 2, then you must reinstall the license on the new server. You can use the same license file for Nexus Repository 3 as for Nexus Repository 2.
The Abort button halts the upgrade and deletes the content created during this upgrade process on the Nexus Repository 3 instance. The Nexus Repository 2 instance is not effected however the upgrade capability must be reset before the upgrade may be restarted.
Everything you've done up to this point is removed, and you must start over.
If you need to attempt this upgrade again, you should follow our instructions for resetting your upgrade and start from scratch.
Interrupting the upgrade or shutting down either Nexus Repository instance during the upgrade requires restarting the upgrade from the beginning. Complete the steps below to reset the upgrade. A brief production outage is required to restart the servers. These steps remove the internal scheduled tasks for the upgrade and any progress made.
Select the Abort button in the upgrade wizard in Nexus Repository 3.
Shut down Nexus Repository 3.
Remove the following from the Nexus Repository 3 data directory.
Delete the content in the file storage paths and the database directory.
${work-dir}/dbDrop and recreate the PostgreSQL database when used
Reconfigure the custom properties file.
${work-dir}/etc/nexus.propertiesClear out all object-based storage from cloud environments.
Shut down Nexus Repository 2 and remove the following directory.
${work-dir}/db/migrationagentRestart Nexus Repository 2
Delete the Upgrade: Agent capability from Nexus Repository 2.