Upgrade Wizard

Nexus Repository includes the Upgrade Wizard used to migrate Nexus Repository 2 to a new Nexus Repository 3 instance. Upgrading to Nexus Repository 3 using the Upgrade Wizard is the preferred method.

Understand the Upgrade Process
Follow the Upgrade Wizard Instructions

Prerequisites for Upgrading

A successful upgrade from Nexus Repository 2 requires planning, decision-making, and testing before attempting the actual upgrade.

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.
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.
The upgrade tool is not supported with Nexus Repository 3 in a highly available deployment.
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.
For resilient deployments, we recommend setting the blobstore outside of the default work directory.
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.
The Nexus Repository 2 instance is on the latest version
- Community Edition (CE): upgrade to the 3.76.0 release with H2. After the upgrade, migrate to the latest release with PostgreSQL.
- Professional (Pro): upgrade directly to the latest version with the PostgreSQL database.
The work directory and files must be owned by the OS user with no zero-length files
Use the following Linux command to find files in the work directory not owned by the 'nexus' user as well as zero-length files:
```
find . \! -user nexus -print
```
Nexus Repository 2 repositories must use distinguishable names
IDs of repositories and repository groups in Nexus Repository 2 that differ only by case will not be accepted during an upgrade to Nexus Repository 3 (example version 2 IDs: myrepoid vs. Myrepoid).
Nexus Repository 2 roles cannot have the ‘nx2’ prefix
This prefix is reserved for Nexus Repository 2 system privileges. Privilege created with the prefix ‘nx2' does not correctly reference its roles. While privileges with this prefix are ported over, they do not contain the assigned permissions.

Deciding on a Data Transfer Method

When performing the upgrade, there are three data transfer methods available: HTTP downloading, file system copying, or file system hard linking.

File System Hard Linking
Nexus Repository 3 creates a file system hard link to the same content on the file system from Nexus Repository 2. The artifacts are not copied rather new links or Inodes are created. New metadata files are created for assets in storage.
Pros: The fastest method, saves storage space.
Cons: Both instances must be installed on the same server.
- Both instances must be configured to access the same storage system on identically named mount points.
- The file system must support hard linking.
- There must be adequate file handles for both instances.
File System Copying
Nexus Repository 3 copies the file content from Nexus Repository 2.
Pros: Faster than downloading, less impact on the performance.
Cons: Not as fast as hard-linking while doubling the storage requirement.
- Both instances must be configured to access the same storage system on identically named mount points.
- Upwards of double the original storage space is needed during the upgrade.
HTTP Downloading
Nexus Repository 3 makes HTTP requests to Nexus Repository 2 to transfer configuration and data.
Pros: The only method that works for situations where Nexus Repository 2 and 3 are on different machines and do not share access to the same file system storage.
Cons: This is the slowest option.
- You must ensure you have enough storage space; upwards of double the original storage space will be needed at least temporarily during data duplication.

Legacy URL Paths

Nexus Repository 2 uses a different URL pattern than Nexus Repository 3 for repositories and groups. Nexus Repository 3 has the capability to support the Nexus Repository 2 URL patterns to avoid breaking requests from your automation build tools and continuous integration pipelines.

The feature supports the following example of URL matching:

Nexus Repository 2 URL Pattern
http://localhost:8081/nexus/content/repositories/maven-central

Nexus Repository 3 URL Pattern
http://localhost:8081/repository/maven-central

This feature does not support REST API calls or the direct repository browsing urls from Nexus Repository 2. Scripts and automated tools written for Nexus Repository 2 need to be rewritten against the Nexus Repository 3 endpoints.

The "NXRM2 style URLs" capability needs to be enabled.
See Capabilities

Optimize Upgrade Performance

Review the following recommendations to speed up the upgrade process. The suggestions below reduce the amount of content to move and free up resources to avoid issues that arise in old repositories.

Disable system feeds
System feeds were used for team communication and are not supported in Nexus Repository 3. Disable system feeds if they are not in use.
Remove the repair index tasks
These tasks support searching components but are not needed while using the Upgrade Wizard. Consider disabling them repositories to improve the server performance.
```
Update Repositories Index
```
See the KB article on the repair Index tasks.
Snapshot Removal Tasks
Run the following tasks to delete unneeded component versions and reduce the amount of content to move.
```
Remove Snapshots from Repository
Remove Unused Snapshots From Repository
```
Deprecated Repositories
Remove deprecated repositories and duplicate proxy repositories. Proxies pointing to sites that don't exist slow the upgrade as Nexus Repository 2 gets hung up trying to contact bad remotes.
See the KB article on removing codehaus.org.
Rebuild Maven Metadata Files Task
Use this task to repair a corrupted Maven repository storage on disk. This may help with errors during the upgrade.
Staging Rules
Redefine or reduce the number of staging rules and profiles.
Scheduled Tasks for Releases
When empty Use Index checkboxes are under the Task Settings, remove those specific tasks.

Advance Options

Configure Timing for Building Search Indexes and Browse Views

The tasks to rebuild search indexes and browse nodes run after an upgrade is completed. In some cases, these tasks may take hours to run while the migration remains in a pending state. This behavior may be modified when you consider it critical for the migration to complete as soon as possible. The search index may be rebuilt asynchronously at a later time.

Add the following file to the Nexus Repository 3 work directory:

<data-dir>/etc/nexus.properties

Update the file with the following settings:

nexus.migration.search.buildDuringMigration=false
nexus.migration.browse.buildDuringMigration=false

Not running these tasks leaves the browse and search data empty in Nexus Repository 3. Remember to schedule the following tasks:

Repair - Rebuild repository browse
Repair - Rebuild repository search

Enable the Continue for an Incomplete Migration

In some cases, the migration utility may fail to enable the Continue option to gracefully finish the migration. Under the direction of Sonatype Support, you may force the migration to continue even when some content may not have been migrated.

Do not select Abort as all migrated content will be lost.
Contact Sonatype Support and inform them of the issue.
When directed by support, add the following file to the Nexus Repository 3 work directory:
```
$data-dir/sonatype-work/nexus3/etc/nexus.properties
```

Add the following property to this file:

nexus.migration.sync.forceContinueEnabled=true

Restart the Nexus Repository 3.
The upgrade wizard will now proceed past the sync phase (step 8 of 9) to finish the upgrade process.