Skip to main content

Moving a Nexus Repository 3 Instance to a New Location

Updated

.

This article provides best practice and considerations for moving an existing Nexus Repository 3 self-hosted standalone server to a new server location under these conditions:

  • Standalone Repository 3 instances not using High Availability
  • OrientDB, H2 and Postgresql Databases
  • Host to Host moves

For Lift-and-Shift to Cloud efforts, please review our help pages.

Basic Requirements

To move a Nexus Repository 3 server to a new location you'll need to move three main things after Nexus Repository is gracefully stopped:

  1. The application directory (e.g. nexus-3.13.0-01)
  2. The data directory (e.g. sonatype-work/nexus3 )
  3. Blob storage

Application Directory

The application directory of a Nexus Repo 3 installation is portable*, and can simply be copied to the new location. Be sure to preserve operating system file permissions when doing this. 

Data Directory

The data directory ( commonly referred to as $data-dir or ${karaf.data} ) of a Nexus Repo 3 installation is portable*, and can just be copied to a new location.

If you're not sure where the data directory of your installation is located, we have an article that can help you. 

DO NOT move the following directories within the $data-dir:

  • cache - temporary files instance specific
  • tmp - temporary files are instance specific

Cautiously move these directories within the $data-dir:

  • elasticsearch

If your last shutdown of the source was not graceful ( abrupt termination ), or in cases files are copied while source NXRM is running, then starting the new target instance with these files present may

  • result in corruption of the Search and Browse views, and certain REST API results in the target instance
  • prevent startup of the target instance

If startup fails or corruption occurs in the target instance due to elasticsearch errors, simply delete the elasticsearch directory in the target and when the target instance restarts, elasticsearch indexes will automatically rebuild.

Optionally move these from $data-dir:

  • logs - logs could be kept instance specific, or if you want to preserve the long term history of a moved instance, include moving these files to the new host

Blob Stores

Blob stores contents are portable and can be copied to a new location, provided the resolved absolute path of a file based blobstore can still be used in the target server. 

File based blob stores: To find the location of your blob stores go to "repository --> blob stores" in the Nexus Repo 3 administration UI. 

If the path shown for a blob store is not an absolute path ( not starting with drive letter on windows or forward slash on other operating systems) , that means it is located at a relative directory under $data-dir/blobs/, and it will be copied when you copy the entire data directory.

If your blob stores are not going to be in the same location as they were in the original system running Nexus Repo you'll need to update their locations in the database.  This is an advanced operation. Check our Relocating Blob Stores article for advice.

If moving blobstores to the cloud, see Migrating Blobs to the Cloud Using Vendor Tools.

Databases

OrientDB and H2 databases are stored in the data directory,so they will be moved when you move the data directory.

Move your Postgresql database using Postgresql native database export and import tools and adjust the database connection settings inside Nexus Repository to point at its new home as needed. 

 

Best Practice

Embedded OrientDB Files

OrientDB files are located under the $data-dir/db directory. Please ensure this advice is followed to avoid embedded OrientDB corruption:

  1. Embedded OrientDB database files must be copied when Nexus Repository is not running
  2. The target location of embedded OrientDB database files must ALWAYS be empty and not contain ANY files from previous copies

Do not use the built in Admin - Export databases for backup task to move a database copy from one instance to another. That is not the purpose of that task. That task should only be used to create backups that could be restored into the exact same instance/location from which they were created.

File Based Blobstores

When using a backup tool that can perform incremental backups, an initial copy of the blobstore contents can be done while the original Nexus Repo 3 is still running. 

If you're using rsync, this can be done using this general process:

  1. Perform an initial sync of File based blobstore data

    rsync -avP <source> <dest>
  2. Shut down Nexus Repository 3

  3. Perform a second copy operation to capture any delta from the first copy:

    rsync -avP --del <source> <dest>

    The --del option ensures the target does not contain any files not present in the source.

If your original system has a slow disk consider running the first rsync with ionice -c3 rsync. This will prevent rsync from consuming all disk bandwidth.

Moving Large Amounts of Data to Cloud Storage

The best performance moving terrabytes(TB) of blobstore data to the cloud requires using cloud native tooling. The built in product features like Repository Export/Import tasks, Change repository blob store task, and Blobstore groups are not intended for moving TB of data more efficiently than native tooling. Please refer to your cloud storage native options:

Amazon Web Services: https://aws.amazon.com/cloud-data-migration/

File Customizations Containing Absolute File Paths

If you've made customizations to the files in the "etc" directory in either the install or data directories, then be sure to check and see if any absolute paths have been used. These may need to be adjusted in the new instance location.

IQ server configuration and Firewall Capabilities

If Firewall: Audit and Quarantine capability has been configured, this new Nexus instance will communicate the existing IQ server. To avoid this, the easiest way is stopping the existing IQ server before starting this Nexus 3, then re-configure the IQ server from the Web UI.

Deployment ID:

The Deployment ID should be unique for each Nexus 3 instance. If this Nexus is a clone of an existing Nexus 3 (not moved), it’s recommended to update the Deployment ID.
NOTE: Deployment ID is NOT exactly same as UUID. An example shell command to generate it is

openssl rand -hex 20 | awk '{print substr($1,1,8) "-" substr($1,9,8) "-" substr($1,17,8) "-" substr($1,25,8) "-" substr($1,33,8)}'

Example SQL:

UPDATE deployment_id SET deployment_id = '{NEW_VALUE}';

PostgreSQL Host Based Authentication

The pg_hba.conf file may contain the IP address of the source Nexus. If so, you’ll need to update the config file and then reload PostgreSQL.

Related articles