Documentation Nexus Repository Manager 3.3

Chapter 20. Upgrading

Available in Nexus Repository OSS and Nexus Repository Pro

20.1. Introduction

Upgrading Nexus Repository Manager presents a necessary step to gain access to new features, bug fixes, performance improvements and other advantages. Regular updates to the latest release are recommended as a general best practice.

Specifically Nexus Repository Manager 3 represents a shift in design that supports a wider set of features requested by customers as well as a platform for a modern, expanded set of functionality. Given these changes, many to the core architecture, the upgrade process requires more attention than in previous versions.

This chapter covers upgrades of Nexus Repository Manager in general. The process of upgrading depends on the specific usage of the repository manager, its configuration and integration with other tools and is potentially complex. Further resources can be found in the Support Knowledge Base.

[Important]

Nexus Repository Manager Pro customers can take advantage of the assistance of the support team.

20.2. Why Upgrade?

As of Nexus Repository Manager 3.1 there is wider feature and functionality equivalency to Nexus Repository Manager 2. Highlights of new functionality include:

  • Expanded repository format support
  • Improved user interface
  • Powerful component search
  • Universal repository browsing
  • Enhanced metadata

Of course, the choice to upgrade depends on the features your team is using and planning to use. In many cases upgrading to version 3 provides an enhanced set of features to support modern development practices and automation. However, it is a good idea to review the support site to compare repository format support, feature equivalency, and compatibility across versions.

20.3. Upgrading from 2.x to 2.y

At a higher level, upgrading from a 2.x release of Nexus Repository Manager to a newer 2.y version typically includes

  • Extracting the new release bundle.
  • Replicating configuration changes.
  • Stopping 2.x instance.
  • Replacing the application directory with the new instance.
  • Starting the new instance.

Further instructions are available on the support site.

20.4. Upgrading from 3.x to 3.y

Upgrades of version 3 are supported for version 3 milestone 7 and later. The upgrade is a similar process to version 2 upgrades and is documented in more detail in the knowledge base article.

[Note]

Follow these specific instructions to upgrade to 3.1.0-4 or later. Since the release of 3.1.0-4, the directory structure has changed for this and later versions.

20.5. Upgrading 2.x to 3.y

Upgrading from Nexus Repository Manager 2 to 3 requires the source repository manager to use version 2.14.1 (or later) and the target repository manager to use version 3.1 (or later).

If the source repository manager uses a version of 2.x that is not 2.14.1 (or later), you must upgrade before starting the upgrade to Nexus Repository Manager 3 as detailed in Section 20.3, “Upgrading from 2.x to 2.y”. Review the version compatiblity matrix, below, for a quick reference.

Version 2 Version 3

2.14.1

3.1

2.14.2

3.2

2.14.3

3.2.1

2.14.4

3.3.1

The target repository manager is typically a fresh installation of the latest 3.x release, with a minimum release version of 3.1. If an existing Nexus Repository Manager 3 is used as the target, it has to be upgraded to 3.1 (or later) as documented in Section 20.4, “Upgrading from 3.x to 3.y”.

[Warning]

Using an existing installation of Nexus Repository Manager 3 populated with data and configuration as the target repository manager incurs restrictions that make the upgrade more complex and potentially requires re-configuring the version 2 instance prior to the upgrade as well as re-configuring Nexus Repository Manager 3 after the upgrade.

20.5.1. Upgrade Process and Expectations

The process of upgrading Nexus Repository Manager 2 to 3, is similar to any major enterprise application upgrade, and should be managed via an upgrade plan. The upgrade plan is really just a specific checklist of all the steps required to perform the upgrade.

While the upgrade process is underway, you can continue to use the source Nexus Repository Manager 2. Any repository content that’s added, updated, or deleted is picked up by the upgrade and added to the target Nexus Repository Manager 3 — however, configuration changes are not.

You should not make changes to items such as realm settings, permissions, roles, role assignments, HTTP configuration, SSL certificates, or add new repositories. These types of configuration changes are not taken into account for an ongoing upgrade and can cause the upgrade process to fail.

20.5.2. What Is Upgraded

As mentioned, Nexus Repository Manager 3 represents an application design shift, involving a new architecture that supports advanced features for today’s development practices. As such, a number of core changes to data stored occur as part of the upgrade process. This includes:

Component storage format from files to blobs
Components in Nexus Repository Manager 2 are stored as individual files on disk. Version 3 stores components as blobs. The conversion process requires version 3 to iterate over every component stored in version 2. This takes the bulk of the time required for the upgrade process.
Settings and metadata
Settings and some component metadata in Nexus Repository Manager 2 are stored across many files. Conversely, Nexus Repository Manager 3 loads equivalent data into an OrientDB database.

20.5.3. What Is Not Upgraded

The file structures within your repository manager environment differs between version 2 and version 3. Before preparing for the upgrade process, review this list of settings and configuration items. These items are not automatically included when you upgrade:

  • custom branding
  • virtual repositories
  • repositories with audit/quarantine enabled
  • Java VM settings, including custom system properties or variables
  • operating system nexus service scripts
  • operating system optimization, such as increasing allowable open file handles
  • environment variables affecting values used to control the repository manager
  • third-party or custom-developed plugins
  • Jetty server XML configuration files
  • unimplemented repository formats
  • manual edits to other files under the nexus installation directory, such as edits to nexus/WEB-INF/classes/ehcache.xml
  • custom log levels or edits to logback.xml configuration files (e.g. custom log file rotation, file naming, log patterns)

There are equivalent configurations possible for all these values and customization in Nexus Repository Manager 3. The specifics vary widely and have to be applied manually after determining the need for such customization and developing specific plans for the modifications. The scope of these modifications varies from zero to large efforts. E.g. some VM start-up parameters might not be appropriate any more due to optimized performance of version 3. On the other hand custom plugin features might now be a standard supported features or require a completely new development effort.

20.5.4. Repository Format Support

Nexus Repository Manager 3 provides support for greatly expanded set of supported repository formats. A complete list of formats is available in a knowledge base article. The list below represents repository formats that can be included in the upgrade process.

  • npm
  • NuGet
  • Site/Raw
  • Maven2
  • RubyGems

20.5.5. Designing Your Upgrade Plan

When upgrading, the most critical decisions you need to make about an upgrade plan are:

  • Identification of a maintenance window for version 2, allowing the upgrade to proceed without interruption.
  • Selection of an installation scenario that best supports your upgrade plan.
  • Selection of an upgrade method.
  • Getting access to a system storage, as well as location for content to be transferred to.
  • Identification of configurations that may result in failure, and prevent upgrade of certain components.
  • Review of security settings, and associated differences between version 2 and version 3.
  • Considerations for optimization.

20.5.6. Supported Installation Scenarios

There are two scenarios for upgrading:

  • Separate servers for version 2 and version 3
  • Version 2 and version 3 running on the same server

20.5.7. Data Transfer Methods

Upgrade is made possible by specific capabilities in version 2 and version 3 called Upgrade: Agent and Upgrade. These capabilities manage the communication between the two servers and can transfer all configuration via web protocols. The bulk of the data to be transferred consists of all the binary components in the repositories that are upgraded. Once the Upgrade: Agent capability, mentioned in Section 20.5.12, “Starting the Upgrade”, is enabled and both repository manager instances are communicating, you can choose one of three methods for this transfer:

  • HTTP Download
  • File System Copying
  • File System Hard Linking

HTTP Downloading

HTTP download is a transfer method in which version 3 makes HTTP requests to version 2 to transfer configuration and data. This is the slowest option.

If version 2 and version 3 are running on different machines and do not share access to the same file system storage, you must use the HTTP download method.

File System Copying

In this transfer method, version 2 tells version 3 the path of the file content to transfer and a simple file system copying is performed.

This upgrade method works if versions 2 and version 3 are configured to access the same storage system on identically named mount points. It is a faster process than the HTTP Download method, and has less impact on the performance of version 2.

File System Hard Linking

In this transfer method, version 2 tells version 3 the path of the file content to transfer and a file system hard link to the same content is created.

This upgrade method works if versions 2 and version 3 are configured to access the same storage system on identically named mount points and hard linking is supported by the file system used. It is the fastest transfer method.

20.5.8. File System Considerations

While discussed in greater detail in Chapter 4, Nexus Repository Manager 3 allows you to create and name multiple blob stores to store your content. Before you start the upgrade process it is important to consider how you want to allocate space within the storage system.

When upgrading, make sure you have enough storage capacity in the destination file system(s). For instance, if you are using hard linking, the data is not duplicated. This saves storage space, but you must ensure that there are enough file handlers available for the content you want to transfer during the upgrade process. On the other hand, file copy and downloading do duplicate your data so upwards of double the original storage space can be, at least temporarily, needed.

20.5.9. Configuration Details for Upgrading

Due to fundamental changes in file structure between Nexus Repository Manager 2 and 3, you should review and compare the configuration details to prevent any failures.

Repository IDs

The Repository ID defined in version 2 is used as the Name for the upgraded repository in Nexus Repository Manager 3 as they define the access URL in both cases. The user-facing Repository Name from version 2 is dropped in the upgrade.

In addition note that IDs of repositories and repository groups in version 2 that differ only by case will not be accepted during an upgrade to version 3 (example version 2 IDs: myrepoid vs Myrepoid). To resolve the ID conflict review and change any IDs in version 2 to distinguishable names.

Repository Groups

Review the contents of the repository groups defined in Nexus Repository Manager 2 to ensure its contents are a selected for upgrade. A single component within the group, not selected, may prevent the entire group from being upgraded.

User Tokens

The upgrade tool only upgrades pre-existing user tokens to version 3, if user token support is enabled in version 2. In version 2, click the User Token tab, in the Administration menu, and enable the setting.

Repository Health Check and SSL Health Check

You can include both your existing Repository Health Check and its corresponding SSL trust store configuration when you upgrade. If you are a Nexus Repository Manager OSS user you only have the ability to upgrade your settings from the Health Check: Configuration capability. If you are a Nexus Repository Manager Pro user, you can also upgrade your existing SSL: Health Check settings. After the upgrade process is complete, settings for both Health Check: Configuration and SSL: Health Check capabilities are enabled in version 3, as they were in version 2.

NuGet API Key

The upgrade tool adds all keys to version 3 that are present in version 2 when asked, even if the NuGet API Key Realm is not active in version 2.

HTTP(S) Proxy Configuration

In general, your HTTP or HTTPS proxy settings for Nexus Repository Manager 2 may not be valid for your Nexus Repository Manager 3 environment. So you need to configure your HTTP or HTTPS proxy settings in version 3 in order to upgrade them to version 2.

If HTTP or HTTPS proxy settings were enabled in your source Nexus Repository Manager 2, the upgrade to your target Nexus Repository Manager 3 might fail because the target could not communicate with the source repository manager. That’s because version 3 could not find a version 2 proxy server in place. Therefore if the HTTP or HTTPS settings were enabled in version 2 during an upgrade, version 3 would use its original HTTP or HTTPS settings, ignoring the settings in place for version 2. Additionally, a warning would be generated in the log if that error occurred.

Licensing

Any Nexus Repository Manager license you have will be applicable between version 2 and version 3. If you are upgrading your versions on the same server, no additional work need be done. If you are upgrading your Nexus Repository Manager 3 to a different server than Nexus Repository Manager 2, then you must reinstall the license on the new server, however, the license files are the same. You do not need a different license for Nexus Repository Manager 3 use.

IQ Server

If you are a Nexus Repository Manager Pro user, and you want to upgrade your source Nexus IQ Server settings and configuration to your target repository manager, ensure that your licenses include the integration for both versions. Your configuration for IQ Server URL, Username, Password, and Request Timeout will be included in the upgrade. Additional configuration, such as analysis properties, trust store usage, and the enabled Nexus IQ Server connection itself will be upgraded from versions 2 to 3.

Repositories that have been configured with the IQ: Audit and Quarantine capability will not be transferred to Nexus Repository Manager 3. If you choose to disable this capability, the repository can be transferred, but quarantine state and audit history will not be retained.

20.5.10. Security Compatibility

Before you upgrade from version 2 to version 3 review the differences in security settings along the upgrade path. Known changes may affect privileges, roles and repository targets. Repository targets no longer exist in Nexus Repository Manager 3 and are replaced by content selectors as documented in Section 4.3.7, “Content Selectors”.

Version 2 Roles

Roles upgraded from version 2 are assigned a Role ID that starts with nx2- in Nexus Repository Manager 3. Role descriptions created during the upgrade process have the word (legacy) in their description.

Version 2 Repository Targets and Target Privileges

If upgrading your repository targets from version 2 to version 3, it is recommended you also upgrade your target privileges and vice versa. If you do not upgrade both, you may find that you need to make further adjustments to version 3 configuration to have things work as they did in version 2.

Repository targets from version 2 are converted to content selectors in version 3. In contrast to repository targets, which rely on regular expressions for user permissions, content selectors use the Java EXpression Language JEXL to perform similar restrictions. The upgrade process modifies repository target names to ensure compatibility with JEXL.

20.5.11. Optimization, Performance, and Tuning

When considering upgrade time and speed, take into account all enabled features on your Nexus Repository Manager 2 instance that you may not need. You can optimize the performance of your upgrade by disabling specific features. As discussed in this article about performance and tuning, identify and then reduce your list of used features to improve the performance of your repository manager. See some highlights, below:

System feeds
If your organization does not rely on system feeds, often used for team communication, learn how to disable them.
Repair index tasks
These tasks support searching components within the user interface, and do not need to be rebuilt that often, consider disabling them across all repositories.
Snapshot removal tasks
Enable both Remove Snapshots from Repository and Remove Unused Snapshots From Repository, which deletes old component versions no longer needed.
Repositories no longer supported
Remove any deprecated repositories. For example, any Maven 2 proxy repositories with the domain name codehaus.org should be deleted.
Rebuild Maven Metadata Files
This scheduled task should only be run if you need to repair a corrupted Maven repository storage on disk.
Staging rules
If you are a Nexus Repository Manager Pro user that uses the application for staging releases, redefine or reduce the number of configured staging rules and staging profiles.
Scheduled task for releases
If you find empty Use Index checkboxes under Task Settings, use the opportunity to disable or remove those specific tasks for releases.

To help you decide how to reduce scheduled tasks, improving the performance of your upgrade, review the knowledge base article.

20.5.12. 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 2.14 or later as documented in Section 20.3, “Upgrading from 2.x to 2.y”.
  2. Install Nexus Repository Manager 3, if upgrading to a new instance
  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:

  1. Preparing, the phase that prepares the transfer and creation of all configuration and components.
  2. Synchronizing, the phase that counts and processes all components set to upgrade and upgrades all other configuration.
  3. Finishing, the phase that performs final clean up, then closes the process.

20.5.13. Enabling the Upgrade Capability in Version 2

In version 2, enable the Upgrade: Agent capability to open the connection for the upgrade-agent. Follow these steps:

  1. Click Administration in the left-hand panel.
  2. Open the Capabilities screen.
  3. Select New to access the Create new capability modal.
  4. Select Upgrade: Agent as your capability Type.
  5. Click Add to close the modal.
  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.

20.5.14. Enabling the Upgrade Capability in Version 3.1 (or later)

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.

20.5.15. 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 two fields, URL and Access Token. 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.
    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.
[Tip]

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).
figs/web/upgrade-repositories-partial.png

Figure 20.1. 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 20.1, “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.

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

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

20.5.17. After the Upgrade

With the upgrade completed and all components transferred, you can perform the next steps in your upgrade plan. These can include:

  • Stop Nexus Repository Manager 2.
  • Archive Nexus Repository Manager 2 and delete the install from the server.
  • Reconfigure Nexus Repository Manager 3 to use the HTTP port, context path and repository paths of version 2, if desired.
  • Alternatively update 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. While automated tools and CI can be reconfigured to utilize the new patterns, it is possible to change a configuration on the Nexus Repository Manager end to allow your upgrade to use the old pattern as well.

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. Once done, this will allow the example of http://localhost:8081/nexus/repository/sample to also be accessed using http://localhost:8081/nexus/content/repositories/sample.

This example (above) 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 above.

[Note]

Any automated tooling that uses direct repository browsing will not function in Nexus Repository Manager 3 as that is not currently supported.