Skip to main content

Step-by-Step Nexus Repository 2 to 3 Upgrade Wizard Instructions

Note

As a best practice, we recommend trying to create a test version of your current production environment so that you can test upgrading from Nexus Repository 2 to 3 there before performing it in a production environment. This can help you see what errors (such as out of memory errors in Nexus Repository 2) may occur with your selected test upgrade settings. Then, you can adjust your settings so that you do not encounter these errors when upgrading your production instance.

Note

The wizard is meant to be used once; do not try to transfer server configuration multiple times.

Follow our instructions for resetting your upgrade before attempting another upgrade.

Are You Ready to Upgrade?

Warning

Before proceeding, have you done the following things?

  • Have you configured the upgrade capabilities in Nexus Repository 2 and 3?

  • Have you performed a test upgrade with your desired upgrade settings using a similar test environment to evaluate any potential issues? (Recommended)

  • Have you ensured that nobody is using the Nexus Repository 3 instance? While this upgrade is happening, Nexus Repository 3 will be offline, and nobody should be using it.

  • Have you upgraded your Nexus Repository 2 instance to the latest version of Nexus Repository 2? (Required)

  • Do both your Nexus Repository 2 and 3 instances have the same licensing setup (both OSS or both Pro)? (Required)

  • Do you need to configure your blob stores in Nexus Repository 3? (See our Storage Guide)

  • Have you evaluated and decided on which transfer method you wish to use and ensured you meet all storage requirements? (See Deciding on a Data Transfer Method)

Step 1 - Configure the Connection Between Nexus Repository 2 and Nexus Repository 3

1. In your Nexus Repository 3 instance, select the Upgrade option from the side menu. This launches the Upgrade wizard and takes you to the Overview screen, which contains important information. Be sure to read this information before proceeding. Then, select Next to navigate to the next screen in the wizard.

126658036.png

2. On the Agent Connection screen, complete the following information:

  • URL - Enter the base URL for the Nexus Repository 2 instance (available in your Application Server Settings).

    • By default, Nexus Repository 2 ships with a /nexus web context that must be included in the URL (e.g., http://<hostname>:<port>/nexus)

  • Access Token - You will need to obtain this from the Nexus Repository 2 instance. This was created whenconfiguring the Upgrade Agent capability in Nexus Repository 2 and is available in your Nexus Repository 2 instance at Administration → Capabilities → Upgrade Agent → Status tab.

126658041.png

  • Fetch Size - This dictates the number of components that Nexus Repository 3 requests from Nexus Repository 2 at one time. It is set to 100 by default.

Warning

Keeping your Fetch Size too high can cause out of memory errors with Nexus Repository 2 and is especially common for NPM and NuGet repositories, which have a lot of package metadata. Consider reducing your fetch size to a smaller value (e.g., 20).

3. Select Next to continue.

Step 2 - Decide What Content to Transfer

1. On the Content screen, select the appropriate checkboxes for what you wish to transfer from your Nexus Repository 2 instance: Repository configuration and content and/or Server configuration. (See Data Included, Excluded, and Changed During Nexus Repository 2 to 3 Upgrade Process.)

Warning

The "Server configuration" checkbox must be selected before proceeding with the migration. This is crucial for the complete and accurate transfer of your server settings and data. Not selecting this option may lead to unpredictable outcomes.

126658462.png

Note

This tool is intended for single use on both repositories and server configuration.

Upgrading repositories in batches or more than once is not supported.

Do not try to transfer server configuration multiple times.

Follow our instructions for resetting your upgrade before attempting another upgrade.

2. Select Next to continue.

Step 3 - Configure and Select Repositories for Upgrade

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)

Note

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.

126658477.png

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.

Note

Repositories that you cannot upgrade to Nexus Repository 3 will appear greyed out and will not be selectable in the list.

126658464.png

4. You can also select the wrench icon in the last column to customize 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.

126658481.png

Step 4 - Run the Upgrade

The upgrade is broken into three phases:

  • Prepare - Prepares the transfer and creation of all configuration 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.

Note

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

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

126659060.png

Note

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.

Step 5 - Finalize the Upgrade

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.

137202509.png

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.

Note

Licensing Note: If you upgraded your versions on the same server, no additional work need 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.

Aborting an Upgrade

If you select the Abort button during the upgrade process, the upgrade stops, and Nexus Repository 3 deletes all of the repositories it has created during this upgrade process.

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.