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.

See Upgrade Wizard for Prerequisites

Overview

The following are an overview of the upgrade process from Nexus Repository 2 to Nexus Repository 3.

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

2. Configure the Connection Between Instances

The Upgrade view is available after the upgrade capability is set. This points Nexus Repository 3 to the Nexus Repository 2 instance to upgrade.

3. Select the Content to Transfer

Select the high-level content to transfer from your Nexus Repository 2 instance.

4. Set the Repository Defaults

Set the storage to use and how Nexus Repository transfers the components.

5. Select the Repositories to Transfer

Select or remove specific repositories to transfer. Modify the storage for specific repositories.

6. Run the Upgrade

Nexus Repository 3 transfers the configuration and artifacts from Nexus repository 2. New artifacts added to Nexus Repository 2 during this phase are still added to the queue to transfer.

Development teams continue to use Nexus Repository 2 until the upgrade is complete.

7. Finalize the Upgrade

Nexus Repository 3 monitors Nexus Repository 2 for new artifacts until the upgrade has been finalized. Nexus Repository 3 indexes all artifacts and is no longer read only.

Development teams switch to use Nexus Repository 3.

Step 1. Set the Upgrade Capability

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

1. Under to Settings → Capabilities, select New under the Capabilities tab.
2. Select Upgrade Agent as the capability type and the Enabled checkbox.
3. Use the generated Access Token or provide your own. Retain this token to use when performing the upgrade.
4. Select Add

Nexus Repository 3 - Upgrade Capability

1. Under Settings → Capabilities, Create an Upgrade capability.
2. Select the Enable this capability checkbox and Create capability.

Step 2. Configure the Connection Between Instances

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

2. Select Next to navigate to the Agent Connection view.

3. 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 /nexus web context that must be included in the URL.

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

5. Set the fetch size as the number of components requested at one time.
6. Select Next to continue.

Step 3. Select the Content to Transfer

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.

Step 4. Set the Repository Defaults

Configure the defaults 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.

Select Next to continue.

Step 5. Select the Repositories to Transfer

1. Select the repositories to transfer to Nexus Repository 3. Repositories that cannot upgrade are not selectable in the list. Select the icon in the last column to modify the upgrade per repository.

2. After selecting Next, review the upgrade configuration. These are the actions taken when running the upgrade.

Step 6. Run the Upgrade

Initiate the upgrade from the Preview screen by selecting Begin where you are directed to the progress view. The upgrade is in three phases:

1. Prepare

Prepares both instances for the upgrade. Configuration changes made in Nexus Repository 2 after the upgrade has started are not moved to Nexus Repository 3.

Select Continue to move to the Synchronizing phase.

2. Synchronizing

Catalogs the components set to upgrade and sets the configuration in Nexus Repository 3.

Monitor the synchronizing screen to observe progress. You may view content in Nexus Repository 3 during the transfer process however, the repositories are offline until the upgrade has been finalized.

3. Finish

Performs the final clean up then closes the process. Nexus Repository 3 continues to check Nexus Repository 2 for new content until the upgrade has been finalized.

Step 7. Finalize the Upgrade

Once a sufficient amount of time has passed since last change to Nexus Repository 2, select continue to finalize the upgrade and move to the finishing view. Changes in Nexus Repository 2 are not no longer synchronized from this point.

Select Done to complete.

• The following task run automatically after an upgrade completes to build the component search and browse indexes.

   Repair - Rebuild repository browse
   Repair - Rebuild repository search

Components may not not be visible during this time until the task "Repo 2 Migration" finishes.

• You may need to reinstall the license on the Nexus Repository instance. Use the same license file for Nexus Repository 3 as for Nexus Repository 2.

Aborting an Upgrade

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 affected, however, the upgrade capability must be reset before the upgrade may be restarted.

Everything done up to this point is removed, and you must start over.

Resetting a Nexus Repository 2 to 3 Upgrade

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.

1. Select the Abort button in the upgrade wizard in Nexus Repository 3.
2. Shut down Nexus Repository 3.
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}/db
     ```
   - Delete blob store contents :
        - **File blob stores:** Delete all contents from `${work-dir}/blobs/` or your configured blob store path.
        - **S3 blob stores:** Delete all objects from the configured S3 bucket.
   - **For PostgreSQL users:** Drop and recreate the PostgreSQL database.

**Note**

Deleting `${work-dir}/db` does NOT remove data from an external PostgreSQL database.
   - Reconfigure the custom properties file.

 ${work-dir}/etc/nexus.properties
 ```

• Clear out all object-based storage from cloud environments.

4. Shut down Nexus Repository 2 and remove the following directory.

   ${work-dir}/db/migrationagent

5. Restart Nexus Repository 2
6. Delete the Upgrade: Agent capability from Nexus Repository 2.