Repository Replication

Only available in Nexus Repository Pro. Interested in a free trial?  Start here.


NEW IN 3.34.0

What is Repository Replication?

Repository replication allows you to publish artifacts to one Nexus Repository Pro instance and make them available on other instances to provide faster artifact availability across distributed teams.

With repository replication, you can manage what binaries can be replicated between two or more instances. The following diagram illustrates the replication process.

 

Prerequisites for Using Replication

In order to use repository replication, you must meet the following prerequisites:

  • Repository replication is only available for Nexus Repository Pro customers; you must have a valid Nexus Repository Pro license to proceed.
  • Source and target repositories must be either Raw, Docker, npm, or Maven hosted repositories.

  • Source and target repository blob stores cannot be part of a blob store group.
  • Ensure the target repository is a newly created hosted repository in one of the supported formats. As a best practice, do not use a target repository that has previously uploaded binaries. This ensures you can maximize the manageability of the storage requirement of replicated content. Note also that the target repository will be read-only to all other requests outside of replication as long as it is used as a target repository.

Prerequisite Steps for Nexus Repository Instances

  1. Download  and install Nexus Repository Pro version 3.34.0 or later in two separate environments following regular installation instructions.
    1. Both Nexus Repository instances must have a hosted repository configured: one will be your source repository, and the other will be your target repository.
    2. The target repository should not be one to which you are deploying components. See Bi-Directional Replication   for details.

      Always use repository replication with two or more instances.

  2. Ensure that a valid Nexus Repository Pro license file is installed in these instances.
  3. Give a user the new Replication Administrator role in each of the target instances. 
  4. If you are running the new Replicator on these same instances, install rsync (for file system blob store replication) or AWS CLI (for S3 blob store replication) in your environments.  For instructions on installing AWS CLI, see the AWS documentation .

In order to run the Replicator, you will also need appropriate permissions to run the Replicator app, rsync, and/or AWS CLI as well as permission to read/write to/from the source and target blob stores.

Additional Prerequisites for Separate Replicator Instances (Optional)

  1. Ensure you are using a Unix, Linux, or Unix/Linux variant operating system; alternatively, you may use Windows 10 with a Linux subsystem. This is required for access to rsync.
  2. Ensure you have Java 8 installed.

Nexus Repository Configuration

Follow these steps to enable repository replication in each instance:

Enable the Capability

  1. Sign in to Nexus Repository as an administrator.
  2. Navigate to Administration > System > Capabilities
  3. Select Create capability .
  4. Select Replication from the list.
  5. Select the Create capability button to enable it.
  6. Verify that you now have access to a new Replication page under Administration > Repository > Replication.
  7. Create and run the new Replication - Backfill blob store attributes with component metadata task 

Running this task initiates a required process that adds necessary metadata to any existing blobs in your Nexus Repository instance. This task may take some time to complete, and you should not attempt to create replication connections until this has completed. You can confirm completion by looking at the task status.

Replication Administrator Role

The pre-configured Replication Administrator role has all six privileges that relate to replication:

Four privileges control access to replication endpoints:

  • nx-replication-read gives the ability to view existing replication endpoints.
  • nx-replication-create gives the ability to view existing replication endpoints and to create new ones.
  • nx-replication-update gives the ability to view existing replication endpoints and to update existing ones.
  • nx-replication-delete gives the ability to view existing replication endpoints and to delete existing ones.

In addition, the following existing privileges are also required to list the available repositories:

  • nx-repository-admin-*-*-edit
  • nx-repository-view-*-*-*

On the source repository, any user with nx-replication-readnx-replication-createnx-replication-update, and nx-repository-view-*-*-* can configure a replication from a source repository; however, they must use a login for a user on the target repository that has the nx-repository-view-*-*-*, nx-repository-admin-*-*-edit, and nx-replication-update permissions.

  1. In the target instance, assign the Replication Administrator role to a local user that can be used to authenticate in the Target Information configuration of a replication connection.

Configure a Replication Connection

At this point, you can continue to configuring a replication connection.

Troubleshooting

Replication loggers provide additional log statements that can be useful for debugging. Complete these steps on both the source and target Nexus Repository instances to see additional replication logs.

  1. Navigate to Administration > Support > Logging
  2. Select  the Create Logger button.
  3. Enter "com.sonatype.nexus.replication" under Logger Name.
  4. Select the DEBUG Logger Level.
  5. Select Save.  

You can use the log viewer to observe any debug information logged by the com.sonatype.nexus.replication logging object.

Files to investigate for troubleshooting include the following:

  • The nexus.log files on both the source and target Nexus Repository instances
    • Located in $data-dir/log/nexus.log
  • The replicator.log file from the CLI app 
    • Located in a logs subdirectory next to where you are running the Replicator CLI
    • Retains up to 30 days worth of logs
    • Contains all rsync and AWS CLI logging