Skip to main content

Configure Global Distribution for Self-Hosted Nexus Repository

Global Distribution allows Nexus Repository to redirect eligible artifact downloads through AWS distribution services. This can improve download performance for users and build systems accessing repositories from different geographic regions.

Global Distribution is available with Nexus Repository Enterprise for installations using Amazon S3 blob stores.

You can configure one of the following distribution methods:

Method

Description

Amazon CloudFront

Delivers artifacts through a content delivery network (CDN). CloudFront can cache downloaded content at edge locations, reducing requests to the originating S3 bucket.

S3 Transfer Acceleration

Routes downloads through AWS's optimized network to the originating S3 bucket. Unlike CloudFront, it does not cache artifacts at edge locations.

CloudFront and S3 Transfer Acceleration cannot be enabled together on the same blob store. Global Distribution must be configured for the S3 blob store and enabled for each repository that uses it. Configuring the blob store alone does not enable Global Distribution for its repositories.

Before You Begin

Before configuring Global Distribution, verify that you have the following:

  • A self-hosted Nexus Repository installation with a valid Enterprise license.

  • An Amazon S3 blob store configured in Nexus Repository.

  • AWS permissions for the selected distribution method:

    • CloudFront: Permissions to configure CloudFront distributions, public keys, key groups, and access to the S3 origin.

    • S3 Transfer Acceleration: Permissions to update the S3 bucket configuration to enable Transfer Acceleration.

Global Distribution applies to eligible binary downloads that support redirects. Some repository formats and request types do not use pre-signed URL redirects. See AWS Pre-Signed URLs for Binary Downloads for supported formats.

Configure Amazon CloudFront

CloudFront uses an S3 bucket as its origin and delivers artifacts through its edge locations. Nexus Repository generates signed CloudFront URLs for eligible downloads.

Take the following steps to configure CloudFront:

  1. Sign in to the AWS Management Console and open CloudFront.

  2. Create a CloudFront distribution using the S3 bucket configured as your Nexus Repository blob store as its origin. Use the bucket's regional S3 endpoint rather than an S3 website endpoint.

  3. Configure origin access control (OAC) and the corresponding S3 bucket policy to allow CloudFront to retrieve objects from the bucket.

  4. Create a cache policy that includes the following query string parameters:

    • response-content-disposition

    • response-content-type

  5. Configure the cache behaviour to use the cache policy. Configure the cache policy's minimum, default, and maximum time-to-live (TTL) settings according to your caching requirements.

  6. Configure signed URL access using a CloudFront public key and trusted key group.

  7. Save the distribution and wait until it is deployed.

The query string parameters allow CloudFront to forward the filename and content-type information associated with the artifact download to S3.

See the AWS documentation for Restricting Access to an S3 Origin and Configuring Signed URLs.

Configure CloudFront Signing Keys

Nexus Repository uses a private key to sign CloudFront download URLs. CloudFront validates these URLs using the corresponding public key.

Take the following steps to configure the signing keys:

  1. Generate a public-private key pair compatible with CloudFront signed URLs.

  2. In CloudFront, register the public key.

  3. Create a key group and associate the public key with it.

  4. Configure the appropriate CloudFront cache behavior to trust the key group.

  5. Keep the private key available for configuration in Nexus Repository.

Record the following information:

Field

Description

Distribution URL

The CloudFront distribution URL, for example, https://d111111abcdef8.cloudfront.net.

Key ID

The identifier of the public key registered in CloudFront.

Private Key

The PEM-formatted private key corresponding to the public key.

Private Key Password

The password used to decrypt the private key, if applicable.

Configure CloudFront Using Terraform

You can also use Terraform to provision the AWS resources required for CloudFront. Your Terraform configuration must provide the CloudFront distribution, S3 origin configuration, cache policy, and public-key infrastructure needed for signed URLs.

Sonatype also provides AWS Reference Architectures with optional CloudFront and S3 Transfer Acceleration configurations for Nexus Repository deployments. Review the reference architecture before adapting it to an existing installation.

If you use a Terraform configuration that defines a bucket_name input variable, initialize and deploy the configuration using the following commands:

terraform init
terraform plan -var="bucket_name=my-nexus-blobstore"
terraform apply -var="bucket_name=my-nexus-blobstore"

Replace my-nexus-blobstore with the name of the S3 bucket used by Nexus Repository.

After deployment, retrieve the CloudFront distribution URL, public key ID, and associated signing private key from your Terraform deployment. If your Terraform configuration defines the outputs distribution_domain and key_pair_id, you can retrieve them using

terraform output distribution_domain
terraform output key_pair_id

Configure S3 Transfer Acceleration

S3 Transfer Acceleration routes data through AWS's optimized network to the S3 bucket. Unlike CloudFront, it does not create cached copies of artifacts at edge locations.

To configure S3 Transfer Acceleration, take the following steps:

  1. Sign in to the AWS Management Console and open Amazon S3.

  2. Select the S3 bucket used by your Nexus Repository blob store.

  3. Open Properties and enable Transfer Acceleration.

  4. Save the configuration.

See Configuring Amazon S3 Transfer Acceleration for additional requirements and limitations.

Note

S3 Transfer Acceleration must be enabled on the S3 bucket before you select it in Nexus Repository.

Configure Global Distribution for an S3 Blob Store

After configuring the distribution method in AWS, enable it for the corresponding S3 blob store in Nexus Repository. Use Nexus One UI to configure Global Distribution.

Take the following steps to configure Global Distribution for an S3 blob store:

  1. Navigate to Settings → Blob Stores.

  2. Create an S3 blob store or open an existing S3 blob store

  3. Locate the Global Distribution step when creating a blob store, or expand Global Distribution when editing an existing blob store.

  4. In Distribution Type, select one of the following options and complete the details:

    • CloudFront

    • S3 Transfer Acceleration

  5. Complete and save the blob store configuration.

When editing an existing CloudFront configuration, Nexus Repository does not display the stored private key. To replace it, select Edit Private Key and provide the replacement key.

A separate Pre-Signed URL checkbox is not required for Global Distribution. When a valid Global Distribution method is configured and available under the Enterprise license, Nexus Repository enables the redirect handling needed to use it.

Enable Global Distribution for Repositories

You can enable Global Distribution for individual repositories or update multiple repositories simultaneously. For existing installations with multiple repositories, use the Global Distribution settings page to enable or disable Global Distribution in bulk.

Enable or Disable Global Distribution for Multiple Repositories

The Repository Distribution Status section allows administrators to enable or disable Global Distribution for multiple existing repositories. To update multiple repositories, take the following steps:

  1. Navigate to Settings → Global Distribution.

  2. Under Repository Distribution Status, locate the repositories you want to update.

  3. Select the checkboxes for the repositories.

  4. Select Enable or Disable.

Nexus Repository displays the result of the operation, including repositories that could not be updated. If Global Distribution is not configured for a repository's S3 blob store, Nexus Repository skips that repository when you attempt to enable Global Distribution in bulk.

The Blob Store Distribution Status section shows whether Global Distribution is configured for supported blob stores. You can use the Configure link to open an S3 blob store that has not yet been configured.

Note

By default, a single bulk update request supports up to 1,000 repositories. You can change this limit using the nexus.globalDistribution.bulkUpdate.maxSize configuration property.

Enable Global Distribution for an Individual Repository

After configuring the S3 blob store, enable Global Distribution for a repository that use it. Take the following steps to enable Global Distribution:

  1. Navigate to Settings → Repositories.

  2. Open the repository you want to configure.

  3. In the Storage section, locate Global Distribution and select Enable Global Distribution.

  4. Save the repository configuration.

Enable Global Distribution by Default for New Repositories

You can configure Nexus Repository to enable Global Distribution automatically when creating new repositories that use an appropriately configured blob store.

Take the following steps to configure the default:

  1. Navigate to Settings → Global Distribution.

  2. Under Global Configuration, select Enable Global Distribution for new repositories by default.

The setting applies to newly created repositories whose blob stores have Global Distribution configured. Existing repositories are not affected when you change this setting.

Global Distribution Configuration Properties

Self-hosted administrators can configure the lifetime of signed download URLs and the maximum number of repositories processed in a bulk Global Distribution request. To modify these settings, add the corresponding properties to your exus.properties file and restart the instance. The following properties are available:

Property

Default

Description

nexus.s3.preSignedUrl.duration

300s

Sets the expiration duration for signed download URLs, including standard S3 and Global Distribution redirects.

nexus.globalDistribution.bulkUpdate.maxSize

1000

Sets the maximum number of repository names allowed in a single bulk Global Distribution update request.

The signed URL expiration duration applies to both standard S3 pre-signed URLs and Global Distribution URLs.