Available in Nexus Repository OSS and Nexus Repository Pro
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.
Nexus Repository Manager Pro customers can take advantage of the assistance of the support team.
As of Nexus Repository Manager 3.1 there is wider feature and functionality equivalency to Nexus Repository Manager 2. Highlights of new functionality include:
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.
Upgrading Nexus Repository Manager 2 to 3 only provides native tooling to transfer content and configurations from the respective source repository manager to the target repository manager. We strongly discourage you to run the upgrade from version 2 to version 3 while simultaneously running any data center-to-data center transfers (e.g. synchronizing applications in your cloud server to on-premises data centers, or vice-versa).
At a higher level, upgrading from a
2.x release of Nexus Repository Manager to a newer
2.y version typically includes
Further instructions are available on the support site.
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.
This must be done before upgrading version 2.x to 3.y.
It is recommended to conduct a comprehensive backup before attempting the upgrade of an HA cluster. This includes a backup of shared blob store filesystems and the data directory on each cluster node.
Currently, Nexus Repository Manager must be stopped on all nodes in the cluster before upgrading each individual node. The software on each node can be upgraded as in Section 20.4, “Upgrading from 3.x to 3.y”, taking care to re-apply any customizations that are not contained in the data directory.
After the software has been upgraded on each node, the nodes can be brought back online one at a time, allowing each node to startup completely before bringing the next node online.
Sonatype recommends using the latest 2.x and 3.y to assure that any fixes in the upgrade process are utilized when upgrading. The latest Nexus Repository Manager versions are verified as compatible before deployment.
Upgrading from Nexus Repository Manager 2 to 3 requires the involved repository managers to use a compatible version of Nexus Repository Manager 2 and 3. If the source repository manager uses a version prior to 2.14.1, you must upgrade it as detailed in Section 20.3, “Upgrading from 2.x to 2.y” before starting the upgrade to Nexus Repository Manager 3. The target repository manager is typically a fresh installation 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”.
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.
If you must upgrade using an older version of Nexus Repository Manager 2, against the recommendations of Sonatype, see the compability matrix to make sure you upgrade to the correct associated version. Upgrading using non-associated versions will result in errors. Also remember, only versions 2.14.1 and beyond can be upgraded.
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.
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:
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:
nexusinstallation directory, such as edits to
logback.xmlconfiguration 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.
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.
When upgrading, the most critical decisions you need to make about an upgrade plan are:
There are two scenarios for upgrading:
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.6.12, “Starting the Upgrade”, is enabled and both repository manager instances are communicating, you can choose one of three methods for this transfer:
When running the HTTP download method, we discourage you from synchronizing repository manager content to cloud services or on-premises data centers. This tool is solely designed to allow for data and configuration transfers between Nexus Repository Manager 2 to 3.
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.
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.
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.
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). To resolve the ID
conflict review and change any IDs in version 2 to distinguishable names.
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.
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.
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.
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.
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.
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:
To help you decide how to reduce scheduled tasks, improving the performance of your upgrade, review the knowledge base article.
After you’ve designed your upgrade plan, considered system performance, and assessed storage needs, there are a few basic steps to start the upgrade:
With the above complete, you can use the upgrade tool in version 3, which guides you through upgrading in three phases:
In version 2, enable the Upgrade: Agent capability to open the connection for the upgrade-agent. Follow these steps:
In the lower section of the Capabilities interface, the repository manager acknowledges the upgrade-agent as Active.
In version 3, enable the Upgrade capability to open the connection for the upgrade-agent, and access the Upgrade tool. Follow these steps:
After you enable the upgrade capabilities, access the upgrade tool in Nexus Repository Manager 3 to start your upgrade.
Select Upgrade located in the System section of the Administration main menu to open the wizard.
http://localhost:8081/nexus/. In the Access Token field, enter the access token, copied from your version 2 Upgrade: Agent capability Status tab.
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 the Nexus Repository Manager 3 after the upgrade for all repositories is done.
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.
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.
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:
With the upgrade completed and all components transferred, you can perform the next steps in your upgrade plan. These can include:
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
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
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.
Any automated tooling that uses direct repository browsing will not function in Nexus Repository Manager 3 as that is not currently supported.