Available in Nexus Repository OSS and Nexus Repository Pro
Repositories are the containers for the components provided to your users as explained in more detail in Repository Manager Concepts. Creating and managing repositories is an essential part of your Nexus Repository Manager configuration, since it allows you to expose more components to your users. It supports proxy repositories, hosted repositories and repository groups using a number of different repository formats.
The binary parts of a repository are stored in blob stores, which can be configured by selecting Blob Stores from the Repository sub menu of the Administration menu.
To manage repositories select the Repositories item in the Repository sub menu of the Administration menu.
A blob store is the internal storage mechanism for the binary parts of components and their assets. Each blob store can be used by one or multiple repositories and repository groups. A default blob store that is based on a file system storage within the data directory configured during the installation is automatically configured.
The Blob Stores feature view available via the Blob Stores item in the Repository sub menu of the Administration menu displays a list of all configured blob stores. The columns provide some detail about each blob store:
the name of the blob store as displayed in the repository administration
the type of the blob store backend; File is available representing a file system-based storage and S3 allows blobs to be stored in AWS S3 cloud storage
the number of blobs currently stored
the size of the blob store
the overall space available for the blob store
Click on a specific row to inspect further details of the selected blob store. The details view displays Type and Name and the absolute Path to the file system storage.
The Create blob store button allows you to add further blob stores. You can configure the Type and Name for the blob store. The Path parameter should be an absolute path to the desired file system location. It has to be fully accessible by the operating system user account running the Nexus repository manager.
Once a blob store has been created it can no longer be modified and any blob store used by a repository or repository group can not be deleted.
Blobs deleted in a repository are only marked for deletion. The Compact blob store task can be used to permanently delete these soft-deleted blobs and therefore free up the used storage space.
Choosing the Number of Blob Stores
You will need to choose how many blob stores to create, and how you allocate repositories to these blob stores. This decision should be based on:
- the size of your repositories
- the rate at which you expect them to grow over time
- the storage space available to your Nexus Repository Manager
- the options you have available for adding storage space
For the time being, once a repository is allocated to a blob store, it is there permanently. Blob stores can be moved from one storage device to another (e.g. to a larger storage device) using a manual process, but blob stores cannot be split, nor can repositories span multiple blob stores. For these reasons, your approach to using blob stores should be chosen carefully.
The simplest approach is to create a single blob store per storage device and divide your repositories among them. This is suitable if either:
- Your repositories are growing slowly enough that you won’t exceed your available storage within a year
- If you exceed available storage, you will be able to move blob stores to larger storage devices.
You should separate repositories into two or more blob stores per storage device if both:
- You expect to exceed your currently available storage within a year
- You cannot move blob stores to larger storage devices, so you must add capacity to Nexus Repository Manager by adding additional storage devices.
The most flexible approach is to create a separate blob store for each repository, although this is not
recommended except in extreme cases of unpredictable capacity because of the administrative complexity.
The current repository-to-blob store limitations will be removed in an upcoming release of Nexus Repository Manager, which will make
it possible to revise your repository/blob store approach over time.
Estimating Blob Store Size
Blob stores contain two files for each binary component stored in Nexus Repository Manager:
- The binary component, stored as a .bytes file (whose size is the same as the component)
- A properties file that stores a small amount of metadata for disaster recovery purposes (<1k)
The total storage size of a blob store is therefore approximately the total size of all of your components, plus an allowance for the properties files and the block size of your storage device. (On average, this will be 1.5 * # of components * block size.)
Choosing the Blob Store Type
NXRM supports two blob store types:
- File blob store: stores the blobs on the filesystem. This is the default blob store type recommended for most installations.
- S3 blob store: stores the blobs in an AWS S3 bucket. This is only recommended for Nexus Repository Manager installations deployed to AWS where storing data to S3 is preferable.
Setting up an S3 Bucket for a Blob Store
Nexus Repository Manager only supports AWS S3. Other implementations of the S3 protocol may or may not work.
Nexus Repository Manager will automatically create an S3 bucket when a blob store is created, if it does not already exist. However, you may also create the bucket yourself. Note that:
- Nexus Repository Manager will automatically apply a lifecycle rule to expire deleted content.
- The bucket can use server-side encryption with KMS key management transparently. Other methods of server side encryption are not supported.
- If running on EC2 instances, Nexus Repository Manager can use the IAM role assigned to those instances when accessing S3 buckets.
Adding a Soft Quota
A soft quota will never block read or write operations on the blob store
The configuration for a soft quota can be found in the Blob Stores feature view, located in the Blob Stores sub menu of the Administration menu. A soft quota is a feature that monitors a blob store and raises an alert when it exceeds a constraint. The initial view displayed in Figure “Example Soft Quota Configuration” shows the parameters of a soft quota:Type of Quota and Quota Limit in MB.
Figure Example Soft Quota Configuration
Space Used and Space Remaining are the two possible choices for Type of Quota. A Space Used quota alerts when the total bytes used by a blob store exceeds the Quota Limit in MB. Space Remaining quotas are triggered when the space available for new blobs drops below the Quota Limit in MB. When a soft quota is violated, that information will be available in the following locations:
- A WARN level message in the logs
- In the Status item in the Support sub menu of the Administration menu, the status of all soft quotas is aggregated in the BlobStores status
- A REST API endpoint
A repository with the type proxy, also known as a proxy repository, is a repository that is linked to a remote repository. Any request for a component is verified against the local content of the proxy repository. If no local component is found, the request is forwarded to the remote repository. The component is then retrieved and stored locally in the repository manager, which acts as a cache. Subsequent requests for the same component are then fulfilled from the local storage, therefore eliminating the network bandwidth and time overhead of retrieving the component from the remote repository again.
By default, the repository manager ships with the following configured proxy repositories:
This proxy repository accesses the Central Repository, formerly known as Maven Central. It is the default component repository built into Apache Maven and is well-supported by other build tools like Gradle, SBT or Ant/Ivy.
This proxy repository accesses the NuGet Gallery. It is the default component repository used by the
nuget package management tool used for .Net development.
A repository with the type hosted, also known as a hosted repository, is a repository that stores components in the repository manager as the authoritative location for these components.
By default, the repository manager ships with the following configured hosted repositories:
This hosted repository uses the maven2 repository format with a release version policy. It is intended to be the repository where your organization publishes internal releases. You can also use this repository for third-party components that are not available in external repositories and can therefore not be retrieved via a configured proxy repository. Examples of these components could be commercial, proprietary libraries such as an Oracle JDBC driver that may be referenced by your organization.
This hosted repository uses the maven2 repository format with a snapshot version policy. It is intended to be the repository where your organization publishes internal development versions, also known as snapshots.
This hosted repository is where your organization can publish internal releases in repository using the NuGet repository format. You can also use this repository for third-party components that are not available in external repositories, that could potentially be proxied to gain access to the components.
A repository with the type group, also known as repository group, represents a powerful feature of Nexus Repository Manager. They allow you to combine multiple repositories and other repository groups in a single repository. This in turn means that your users can rely on a single URL for their configuration needs, while the administrators can add more repositories and therefore components to the repository group.
The repository manager ships with the following groups:
The maven-public group is a repository group of maven2 formatted repositories and combines the important external proxy repository for the Central Repository with the hosted repositories maven-releases and maven-snapshots. This allows you to expose the components of the Central Repository as well as your internal components in one single, simple-to-use repository and therefore URL.
This group combines the nuget formatted repositories nuget-hosted and nuget.org-proxy into a single repository for your .Net development with NuGet.
Managing Repositories and Repository Groups
The administration user interface for repositories and repository groups is available via the Repositories item in the Repository sub menu of the Administration menu. It allows you to create and configure repositories as well as delete them and perform various maintenance operations. The initial view displayed in Figure 4.6, “List of Repositories” features a list of all configured repositories and repository groups.
Figure 4.6. List of Repositories
The list of repositories displays some information for each repository in the following columns:
the unique name of the repository or repository group
the type of the repository with values of proxy or hosted for repositories or group for a repository group
the repository format used for the storage in the repository with values such as maven2, nuget or others
the status of the repository as well as further information about the status. A functioning repository would show the status to be Online. Additional information can e.g., be about SSL certification problems or the status of the remote repository for a currently disabled proxy repository
the copy button prompts a dialog containing a direct URL path exposing the repository
displays the repository health statistics from a previously run Repository Health Check, or a button to start the analysis
The Create repository button above the repository list triggers a dialog to select the Recipe for the new repository. The recipe combines the format and the type of repository into a single selection. Depending on your repository manager version and installed plugins, the list of available choices differs.
For example to create another release repository in maven2 format, you would click on the row with the recipe maven2 (hosted) in the dialog. If you wanted to proxy a maven2 repository, choose maven 2 (proxy). On the other hand if you want to proxy a nuget repository, choose nuget (proxy). With maven2 (group) you can create a repository group for maven2 repositories.
After this selection, you are presented with the configuration view, that allows you to fill in the required parameters and some further configuration. The exact details on the view depend on the selected repository provider and are identical to the administration for updating the configuration of a repository documented in the following sections.
Once you have created a repository or repository group, it is available in the list for further configuration and management. Clicking on a specific row allows you to navigate to this repository specific administration section. An example for the maven-central repository is partially displayed in Figure 4.7, “Partial Repository Configuration for a Proxy Repository”.
Figure 4.7. Partial Repository Configuration for a Proxy Repository
The repository administration feature view has buttons to perform various actions on a repository. The buttons displayed depend on the repository format and type. The following buttons can be found:
The Delete repository button allows you to delete the repository and all related configuration and components, after confirming the operation in a dialog.
The Invalidate cache button invalidates the caches for this repository. The exact behavior depends on the repository type:
Invalidating the cache on a proxy repository clears the proxy cache such that any items cached as available will be checked again for any changes the next time they are requested. This also clears the negative cache for the proxy repository such that any items that were not found within the defined cache period will be checked again the next time they are requested.
Invalidating the cache of a repository group, clears the group cache such that any items fetched and held in the group cache, such as Maven metadata, will be cleared. This action also invalidates the caches of any proxy and group repositories that are members of this group.
The Rebuild Index button allows you to drop and recreate the search index for the proxy repository, synchronizing the contents with search index. This button is only available for proxy repositories.
The following properties can be viewed for all repositories and can not be edited after the initial creation of the repository:
The Name is the identifier that will be used in the URL for access to the repository. For example, the proxy repository for the Central Repository has a name of maven-central. The Name must be unique in a given repository manager installation and is required.
Format defines in what format the repository manager exposes the repository to external tools. Supported formats depend on the edition of the repository manager and the installed plugins. Examples are maven2, nuget, raw, docker, npm, and others.
The type of repository - proxy, hosted, or group.
It shows the user facing URL this means that Maven and other tools can access the repository directly at e.g.,
The checkbox allows you set whether this repository is available to client side tools or not.
Beyond the generic fields used for any repository, a number of different fields are used and vary depending on the repository format and type. They are grouped under a number of specific headers that include configuration for the related aspects and include:
- Negative Cache
- Maven 2
- and others
Every repository needs to have a Blob store configured to determine where components are stored. The drop-down allows you to select from all the configured blob stores. Documentation about creating blob stores can be found in Blob Stores.
The Strict Content Type Validation allows you to activate a validation that checks the MIME type of all files published into a repository to conform to the allowed types for the specific repository format.
This section allows hosted and proxy repositories to select a cleanup policy to run to keep the contents of that repository from getting larger than intended. Ultimately, this is a way of controlling your disk space and making sure unused items are removed from NXRM. The use of this is optional and the default field is None.
The dropdown will only include cleanup policies you have created for the respective format. See here for more about creating and maintaining cleanup policies.
Groups do not use cleanup policies themselves, they simply host the components from their children.
A hosted repository includes configuration of a Deployment policy in the Hosted configuration section. Its setting controls how a hosted repository allows or disallows component deployment.
If the policy is set to Read-only, no deployment is allowed.
If this policy is set to Disable redeploy, a client can only deploy a particular component once and any attempt to deploy a component again will result in an error. The disabled redeploy is the default value, since most client tools assume components to be immutable and will not check a repository for changed components that have already been retrieved and cached locally.
If the policy is set to Allow redeploy, clients can deploy components to this repository and overwrite the same component in subsequent deployments.
The configuration for proxy repositories in the Proxy section also contains the following parameters:
A proxy repository on the other hand requires the configuration of the Remote Storage. It needs to be configured with the URL of the remote repository, that should to be proxied. When selecting the URL to proxy it is beneficial to avoid proxying remote repository groups. Proxying repository groups prevents some performance optimization in terms of accessing and retrieving the content of the remote repository. If you require components from the group that are found in different hosted repositories on the remote repository server it is better to create multiple proxy repositories that proxy the different hosted repositories from the remote server on your repository manager instead of simply proxying the group.
Use the Nexus truststore
This checkbox allows you to elect for the repository manager to manage the SSL certificate of the remote repository. It is only displayed - if the remote storage uses a HTTPS URL. The View certificate button triggers the display of the SSL certificate details in a dialog. The dialog allows you to add or remove the certificate from the certificate truststore maintained by the repository manager. Further details are documented in Outbound SSL - Trusting SSL Certificates of Remote Repositories.
Setting a repository to blocked causes the repository manager to no longer send outbound requests to the remote repository.
Auto blocking enabled
If Auto blocking enabled is set to true, the repository manager automatically blocks a proxy repository if the remote repository becomes unavailable. While a proxy repository is blocked, components will still be served to clients from a local cache, but the repository manager will not attempt to locate an component in a remote repository. The repository manager periodically retests the remote repository and unblocks it once it becomes available.
Maximum component age
When the proxy receives a request for a component, it does not request a new version from the remote repository until the existing component is older than Maximum component age .
Maximum metadata age
The repository manager retrieves metadata from the remote repository. It will only retrieve updates to metadata after the Maximum metadata age has been exceeded. If the metadata is component metadata, it uses the longer of this value and Maximum component age before rechecking.
Not found cache enabled/Not found cache TTL
If the repository manager fails to locate a component, it will cache this result for a given number of minutes. In other words, if the repository manager can’t find a component in a remote repository, it will not perform repeated attempts to resolve this component until the Not found cache TTL time has been exceeded. The default for this setting is 1440 minutes (or 24 hours) and this cache is enabled by default.
The HTTP configuration section allows you to configure the necessary details to access the remote repository, even if you have to provide authentication details in order to access it successfully or if you have to connect to it via a proxy server.
This configuration is only necessary, if it is specific to this repository. Global HTTP proxy and authentication is documented in HTTP and HTTPS Request and Proxy Settings.
This section allows you to select Username or Windows NTLM as Authentication type. Subsequently you can provide the required Username and Password for plain authentication or Username, Password, Windows NTLM hostname and Windows NTLM domain for Windows NTLM-based authentication.
HTTP request settings
In the HTTP request settings you can change properties of the HTTP requests to the remote repository. The values you can apply to this section are:
Enter the string to be appended to user-agent HTTP headers.
Enter the total number of connection attempts after an initial timeout.
Set the timeout interval for requests, in seconds.
Enable circular redirects
Allow proxy repositories to follow redirects indicated by the remote server even if they point to an already processed URL.
Authorize HTTP cookies sent by the remote server, for future requests.
https://maven.oracle.com is a server that requires both Enable circular redirects and Enable cookies. This is because, when requesting data you are redirected to a queue of different URLs, most of which are involved with authentication.
By enabling these options, you allow the repository manager to maintain the authentication state in a cookie that would be sent with each request, eliminating the need for the authentication-related redirects and avoiding timeouts.
Changes made to HTTP request settings are applied to all HTTP requests made from the repository manager to the remote repository being proxied. Enabling these settings will override any general settings defined in HTTP and HTTPS Request and Proxy Settings.
Some repository formats include configuration options, such as these formats:
- Repository Connectors, Docker Registry API Support, and (for proxies) Docker Index for Docker repositories
- Maven 2 for Maven repositories: Maven Repository Format
- NuGet for NuGet proxy repositories: NuGet Repository Format
- Bower for Bower proxy repositories: Proxying Bower Repositories
- Yum for Yum hosted repositories: Hosting Yum Repositories
The creation and configuration for a repository group differs a little from pure repositories. It allows you to manage the member repositories of a repository group. An example for a repository group using the maven2 format is visible in Figure 4.8, “Repository Group Configuration”. In this figure you can see the contents of the maven-public group that is pre-configured in Nexus Repository Manager.
Figure 4.8. Repository Group Configuration
The Format and Type are determined by the selection of the provider in the creation dialog e.g., maven2 (group) for the maven-public as a maven2 format repository group.
The Name is set during the creation and is fixed once the repository group is created.
The Online checkbox allows you set whether this repository group is available to client side tools or not.
The Member repositories selector allows you to add repositories to the repository group as well as remove them. The Members column includes all the repositories that constitute the group. The Available column includes all the repositories and repository groups that can potentially be added to the group.
Note that the order of the repositories listed in the Member section is important. When the repository manage searches for a component in a repository group, it will return the first match. To reorder a repository in this list, click and the drag the repositories and groups in the Members list or use the arrow buttons between the Available and Members list. These arrows can be used to add and remove repositories as well.
The order of repositories or other groups in a group can be used to influence the effective metadata that will be retrieved by Maven or other tools from a repository group. It is recommended practice to place hosted repositories higher in the list than proxy repositories. For proxy repositories, the repository manager needs to check the remote repository which will incur more overhead than a hosted repository lookup.
It is also recommended to place repositories with a higher probability of matching the majority of components higher in this list. If most of your components are going to be retrieved from the Central Repository, putting maven-central higher in this list than a smaller, more focused repository is going to be better for performance, as the repository manager is not going to interrogate the smaller remote repository for as many missing components. These best practices are implemented in the default configuration.
Repository Management Example
The following sections detail some common steps of your repository management efforts on the example of a maven2 repository.
Adding Repositories for Missing Dependencies
If you’ve configured your Maven
settings.xml or other build tool configuration to use the maven-public repository group as a mirror for all repositories, you might encounter projects that are unable to retrieve components from your local repository manager installation.
More details about client tool configuration for Maven repositories can be found in Maven Repositories.
This usually happens because you are trying to build a project that has defined a custom set of repositories and snapshot repositories or relies on the content of other publicly available repositories in its configuration. When you encounter such a project all you have to do is add this repository as a new maven2 format, proxy repository and then add the new proxy repository to the maven-public group.
The advantage of this approach is that no configuration change on the build tool side is necessary at all.
Adding a New Repository
Once you have established the URL and format of the remote repository you are ready to configure the repository. E.g. the JBoss.org releases repository contains your missing component. Click on the Create repository button in the Repositories feature view and click on maven2 (proxy) from the list in the dialog.
In the configuration dialog:
- Set Name to jboss-releases
- Set Remote storage to
- For a maven2 format repository, confirm that the Version policy is set correctly to Release.
- Click on the Create repository button at the end of the form
The repository manager is now configured to proxy the repository. If the remote repository contains snapshots as well as release components, you will need to repeat the process creating a second proxy repository with the same URL setting version policy to Snapshot.
Adding a Repository to a Group
Next you will need to add the new repository jboss-releases to the maven-public repository group. To do this, click on the row of the maven-public group in the Repositories feature view.
To add the new repository to the public group, find the repository in the Available list on the left, click on the repository you want to add and drag it to the right to the Members list. Once the repository is in that list, you can click and drag the repository within that list to alter the order in which the group will be searched for a matching component. Press the Save button to complete this configuration.
In the last few sections, you learned how to add new repositories to a build in order to download components that are not available in the Central Repository.
If you were not using a repository manager, you would have added these repositories to the repository element of your project’s POM, or you would have asked all of your developers to modify
~/.m2/settings.xml to reference two new repositories. Instead, you used the repository manager to add the two repositories to the public group. If all of the developers are configured to point to the public group, you can freely swap in new repositories without asking your developers to change local configuration, and you’ve gained a certain amount of control over which repositories are made available to your development team. In addition the performance of the component resolving across multiple repositories will be handled by the repository manager and therefore be much faster than client side resolution done by Maven each time.
Content selectors provide a means for you to select specific content from all of your content. The content you select is evaluated against expressions written in CSEL (Content Selector Expression Language). CSEL is a light version of JEXL used to script queries along specific paths and coordinates available to your repository manager formats.
What Happened to JEXL?
We discovered that JEXL based content selectors weren't meeting performance expectations. To address this we introduced CSEL based selectors to support changes coming in future releases. When you upgrade, Nexus Repository will automatically upgrade as many of your existing JEXL selectors to CSEL selectors as possible. Any remaining JEXL selectors will continue to function, but we encourage you to perform an upgrade as soon as possible.
Content selectors allow you to define what content users are allowed to access. You can define, in a simplified example, a selector named "Apache Maven" with a search expression of path =~ "^/org/apache/maven/". This would match all components that start with the designated component path.
Creating a Query
Before you identify user permissions for your selector, create the query first. Click Content Selectors located in Repository, from the Administration menu. Click Create selector to open a new form.
In the Selector ID section enter a Name and (optional) Description of your selector in the corresponding fields. In the Specification section use the Search expression field to build your query using CSEL syntax.
You can preview your selector and what results it will return by clicking the Preview results button. On click, a modal will appear as shown in Figure 4.9, “Content Selector Preview Modal”. The Expression field will automatically be filled in with anything you had in the Search expression field. Similarly, any changes to Expression will be saved to the Search expression when you close the preview.
Figure 4.9. Content Selector Preview Modal
To see results your selector would find, select a repository or grouping of repositories from the Preview Repository dropdown and click the Preview button. Assets that match will be returned in the space below the filter and can be filtered upon if you wish to check on a specific result. The Name column is also sortable in ascending or descending order. Close returns you to the content selector creation screen.
Once you are satisfied with your fields, click Create selector to create the Content Selector. All saved selector queries you create will be listed in the Content Selectors screen.
Managing Selector Permissions
As part of your security setup, you can create user permissions to manage the filters you built in the Create Selector form. You can add a new privilege that controls operations such as read, edit, delete, and * (all), for components matching that selector. The privilege can even span multiple repositories.
To create a new content selector privilege, click Privileges in the Security section of the Administration panel. Then click the Create Privilege button. Locate and click Repository Content Selector from the list of options in Select Privilege Type. You will see a form that displays the following:
Name: Create a name for the content selector privilege.
Description: Add a brief description for the privilege.
Content Selector: Use this dropdown to select from a list of selectors you created.
Repository: Use this dropdown to select from either a range of all repository contents, all repository contents of an individual format, or repositories created by you.
Actions: Grant read, edit, delete, or * (all) privileges for user access control.
To complete the form, save the new privilege by clicking Create privilege. You can use your new privilege to regulate what permissible data you want the user to access. You could group all related privileges into a role as documented in Roles. Ultimately, you could assign your roles to a user, as mentioned in Users.
A practical example might be where you delegate all control of components in org.apache.maven to a "Maven" team. This way, you would not need to create separate repositories for each logical division of your components.
Content Selector Reference
Below are the allowable attributes for content selectors that define path, format, and coordinate as values supported by Nexus Repository Manager.
|path||The path of your repository content|
|format||The format of the content for which you query|
|coordinate||A map of attributes that differ by content format|
This table contains a description of attributes that can affect the respective formats. See the examples below, for sample format queries against specific coordinates.
|Available Formats||Coordinate Attributes|
Content Selector Examples
Matches text exactly.
e.g. format == "raw"
Matches a Java regular expression pattern.
e.g. path =~ "^/org/apache/commons/.*"
Starts with text.
e.g. path =^ "/com/example/"
Match all expressions.
e.g. format == "maven2" and path =~ "^/org/apache/commons/.*"
Match any expression.
e.g. format == "maven2" or format == "npm"
- ( expr )
Group multiple expressions.
e.g. format == "npm" or (format == "maven2" and path =~ "^/org/apache/commons/.*")
Select all raw format content
format == "raw"
Select all maven2 content along a path that starts with org.apache.commons
format == "maven2" and path =~ "^/org/apache/commons/.*"
When writing a content selector, remember that the asset’s path will always begin with a leading slash when the selector is evaluated. This is true even though the leading slash is not displayed when searching or browsing assets.