Upgrade Procedures

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:

  1. Upgrade your existing version 2 instance to the latest available 2.x version as documented in Upgrading from 2.x to 2.y.
  2. If you have not already, install Nexus Repository Manager 3.
  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:

  1. Click to expand Administration in the left-hand panel.
  2. Click the Capabilities menu item to open the respective screen.
  3. Click the New button to access the Create new capability modal.
  4. Select Upgrade: Agent as your capability Type.
  5. Click Add to close the modal and add the capability.
  6. Copy and save the Access Token found on the Status tab for your new capability. You need it to configure the Upgrade tool in 
    version 3.

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:

  1. Click Capabilities in the System section of the Administration main menu to open the Capabilities feature view.
  2. Click Create capability.
  3. Select Upgrade, then click Create capability to enable the upgrade capability.

Upgrading Content

After you enable the upgrade capabilities, access the upgrade tool in Nexus Repository Manager 3 to start your upgrade.

  1. Go to the Administration menu.
  2. Select Upgrade located in the System section of the Administration main menu to open the wizard.

Overview

The upgrade tool provides an overview of what is allowed for an upgrade as well as warnings on what cannot be upgraded.

Agent Connection

This screen presents three fields: URL, Access Token, and Fetch Size. 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. The Fetch Size determines how many assets are transfered at once from version 2 server to version 3; lowering the default value can mitigate memory or time out issues.

Content

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.


Repository Defaults

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: Partial List of Repository Selections for Upgrade

Repositories

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: 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.

Preview

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.

Upgrade Scenarios

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 http://localhost:8081/nexus/repository/sample to also be accessed using http://localhost:8081/nexus/content/repositories/sample.

Note

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.

This capability has no affect on REST API calls because these were totally rewritten in NXRM3. Any REST API calls need to be reevaluated and rewritten against the NXRM3 REST API.

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:

org.sonatype.nexus.repository.httpbridge.internal.HttpBridgeModule.legacy=true

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:

  1. Shut down Nexus Repository Manager 2 and remove the entire NXRM$work-dir/db/migrationagent directory.
  2. Shut down Nexus Repository Manager 3 and remove the entire NXRM$data-dir directory.