Starting the Upgrade
After you’ve designed your upgrade plan, considered system performance, and assessed storage needs, there are a few basic steps to start the upgrade:
- Upgrade your existing version 2 instance to the latest available 2.x version as documented in Upgrading from 2.x to 2.y.
- If you have not already, install Nexus Repository Manager 3.
- Enable the upgrade capabilities in both version 2 and version 3.
With the above complete, you can use the upgrade tool in version 3, which guides you through upgrading in three phases:
- Preparing, the phase that prepares the transfer and creation of all configuration and components.
- Synchronizing, the phase that counts and processes all components set to upgrade and upgrades all other configuration.
- Finishing, the phase that performs final clean up, then closes the process.
Enabling the Upgrade Capability in Version 2.x
In version 2, enable the Upgrade: Agent capability to open the connection for the upgrade-agent.
Follow these steps:
- Click to expand Administration in the left-hand panel.
- Click the Capabilities menu item to open the respective screen.
- Click the New button to access the Create new capability modal.
- Select Upgrade: Agent as your capability Type.
- Click Add to close the modal and add the capability.
- Copy and save the Access Token found on the Status tab for your new capability. You need it to configure the Upgrade tool in
In the lower section of the Capabilities interface, the repository manager acknowledges the upgrade-agent as Active.
Enabling the Upgrade Capability in Version 3.x
In version 3, enable the Upgrade capability to open the connection for the upgrade-agent and access the Upgrade tool.
Follow these steps:
- Click Capabilities in the System section of the Administration main menu to open the Capabilities feature view.
- Click Create capability.
- Select Upgrade, then click Create capability to enable the upgrade capability.
After you enable the upgrade capabilities, access the upgrade tool in Nexus Repository Manager 3 to start your upgrade.
- Go to the Administration menu.
- Select Upgrade located in the System section of the Administration main menu to open the wizard.
The upgrade tool provides an overview of what is allowed for an upgrade as well as warnings on what cannot be upgraded.
This screen presents two fields: URL and Access Token. In the URL field, enter the URL of your version 2 server including the context path e.g.
http://localhost:8081/nexus/. In the Access Token field, enter the access token, copied from your version 2 Upgrade: Agent capability Status tab.
This screen allows you to select from Repository configuration and content, which includes user accounts and associated security settings, and Server configuration. Check the options that apply.
The Repository configuration and content upgrades all user accounts when selected. If certain user accounts aren’t desired in Nexus Repository Manager 3 then you can delete them from Nexus Repository Manager 3 after the upgrade for all repositories is done.
The Repository Defaults screen allows you to select the directory destination and transfer method. The first drop-down menu, Destination, allows you to pick a blob store name different from default. The second drop-down menu, Method, allows you to choose the transfer method. This section allows you to click and change each repository’s individual transfer method and destination (i.e. blob store).
Figure 20.1. Partial List of Repository Selections for Upgrade
If User-Managed Repositories is one of your selections from the Content screen, the Repositories screen allows you to select which repositories you want to upgrade. As shown in Figure 20.1, Partial List of Repository Selections for Upgrade, you can select all repositories with one click, at the top of the table. Alternatively, you can select each individual repository and customize upgrade options for each repository with the configuration icons in the last column. In addition to Repository, the table displays information about the status of the repository. Keep in mind that the Repository ID defined in version 2 is displayed in the list and after the upgrade used as the Name of the repository.
This table displays a preview of the content set for the upgrade, selected in the previous screens. Click Begin, then confirm from the modal, that you want to start the upgrade process.
Running the Upgrade
After the upgrade was started in the Preview screen, the repository manager starts with a short Preparing step. From this point on, no further configuration changes should be performed on version 2. They will not be moved to version 3.
Any upgrade process invoked destroys any existing configuration in the target Nexus Repository Manager 3 server and replaces it with the upgraded configuration from version 2.
However, any content changes to the upgraded repositories continue to be upgraded during the following Synchronizing step. For example, new proxied components or new deployed components in version 2 are transferred to version 3.
During the transfer process, your content can already be viewed and accessed in version 3, for example via using the component search or browsing in repositories or repository groups. However, the repositories will be offline until the process is fully complete.
The status in the view shows the number of components transferred and when the last changes where detected in version 2. Once all components are migrated and no further changes have been detected for a while the upgrade is mostly complete. You can now decide upon waiting for further deployments (and component evaluations in the case of Nexus Firewall) to version 2 or finalizing the upgrade. To finalize, stop the monitoring and proceed through the Finishing screen.
You can transfer all components at once, but the time to complete these steps depends on the amount of components transferred. This can range from minutes to hours and potentially beyond. With that in mind, your upgrade plan allows you to transfer repositories and repository configurations, incrementally.
When you upgrade individual repositories, the content can only be transferred once. When the repository content is transferred to Nexus Repository Manager 3, it can’t be upgraded again unless it’s removed from the target. However, upgrading content from your Security or System options has a different operation. These are non-repository configurations. If transferred from a previous upgrade, the new upgrade will overwrite the existing non-repository configurations in Nexus Repository Manager 3.
Typically an upgrade should be treated as a single process that potentially spans multiple steps. These can be separate invocations of the upgrade tool with verification on the target Nexus Repository Manager 3 in between. Repeated upgrade of repositories includes the related configuration such as repository targets/content selectors and related security configuration. It is destructive to configuration from a prior upgrade. Keeping this in mind, here are a few possible alternative steps you can perform:
- transfer everything, abort at any stage, then re-initiate a second upgrade after modifications on the source Nexus Repository Manager 2
- transfer non-repository configuration and several repositories, then return to upgrade the rest of the repositories
- transfer all content, and then upgrade everything a second time (though, previously upgraded repositories can not be selected)
- transfer non-repository configuration, then optionally return and upgrade all repositories
After the Upgrade
With the upgrade completed and all components transferred, you can perform the next steps in your upgrade plan. These can include:
- Stopping Nexus Repository Manager 2.
- Archiving Nexus Repository Manager 2 and delete the install from the server.
- Reconfiguring Nexus Repository Manager 3 to use the HTTP port, context path and repository paths of version 2, if desired.
- Alternatively updating all tool configurations pointing to the repository manager, such as Maven settings files and POM files.
Configuring Legacy URL Paths
By default, Nexus Repository Manager 2 uses a different URL pattern to expose repositories and repository groups than Nexus Repository Manager 3. During upgrade from NXRM 2 to NXRM 3, a capability is added so that Nexus Repository Manager 3 automatically supports the old patterns and your automated tools and CI continue to work. This allows the example of to also be accessed using
This example assumes your hostname (
localhost), port (
8081) and context path (
nexus) match between your Nexus Repository Manager 2 and Nexus Repository Manager 3 installations. If not, you must utilize the ones from version 3 or reconfigure as stated in Changing the Context Path section.
Pre 3.7, if you want the old URL format, you must make a configuration change. This can be done in
$data-dir/nexus3/etc/nexus.properties by adding:
As with any Nexus Repository Manager configuration change, the server must be restarted for this to start working.
Any automated tooling that uses direct repository browsing will not function in Nexus Repository Manager 3 as that is not currently supported.
Restarting an Upgrade
If you are running a Nexus Repository Manager 2 to 3 upgrade and it needs to be restarted for some reason (the upgrade was cancelled, or a problem occurred) it will be necessary to start the upgrade over from the beginning. To do this:
- Shut down Nexus Repository Manager 2 and remove the Nexus 2 $work-dir/db/migrationagent directory.
- Shut down Nexus repository Manager 3 and remove the entire Nexus 3 $data-dir.