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. Thus, 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.

What Is Upgraded

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.


By default, Nexus Repository Manager 2 uses a different URL pattern to expose repositories and repository groups than Nexus Repository Manager 3. A capability is added during upgrade to allow your automated tools and CI to use the old patterns.

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
  • 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
  • repository formats unimplemented in NXRM3
  • 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)
  • tasks (called scheduled tasks in NXRM2)
  • capabilities
  • the admin user password from NXRM2
  • staging repositories, settings, or configuration
  • some existing artifact information based on NXRM2 data such as uploadedBy, uploadedDate, lastModified (is replaced by "system" value and date of migration)

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.

Repository Format Support

Nexus Repository Manager 3 supports an evolving set of repository formats. The automatic repository upgrade procedure from 2 to 3 has certain limitations.

Upgradable Formats

  • Maven2 ( excluding staging repositories )
  • npm
  • NuGet
  • Site ( called Raw in NXRM3 )
  • RubyGems

Upgrade with Limited Support

Upgrade Not Supported

  • Maven1
  • P2
  • OBR

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.

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