# 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](https://help.sonatype.com/en/nexus-repository-3-upgrade-wizard.html "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](https://help.sonatype.com/en/upgrade-wizard-instructions.html#step-1--set-the-upgrade-capability_body) 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](https://help.sonatype.com/en/upgrade-wizard-instructions.html#step-2--configure-the-connection-between-instances_body) 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](https://help.sonatype.com/en/upgrade-wizard-instructions.html#step-3--select-the-content-to-transfer_body) 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](https://help.sonatype.com/en/upgrade-wizard-instructions.html#step-4--set-the-repository-defauts_body) 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](https://help.sonatype.com/en/upgrade-wizard-instructions.html#step-5--select-the-repositories-to-transfer_body) 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](https://help.sonatype.com/en/upgrade-wizard-instructions.html#step-6--run-the-upgrade_body) 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](https://help.sonatype.com/en/upgrade-wizard-instructions.html#step-7--finalize-the-upgrade_body) 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](https://help.sonatype.com/en/upgrade-wizard-instructions.html#aborting-an-upgrade_body) 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](https://help.sonatype.com/en/upgrade-wizard-instructions.html#resetting-a-nexus-repository-2-to-3-upgrade_body) 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.