Warning
The OSGi bundle capability has been removed from the Nexus Repository as of version 3.78.0. Any installations using bundles when upgrading to this version will find that the bundles are not loaded.
This page is only for information purposes for prior releases.
Nexus Repository is built on top of the OSGi container Apache Karaf. This supporting core infrastructure provides a foundation for these editions. The functionality is encapsulated in several OSGi bundles. Each edition is composed of several bundles, that provide specific features.
Bundles can provide further functionality for the back end such as support for new repository formats, specific behavior for components, new tasks, and any other additional functionality as well as new user interface components and modifications. They can also group a number of these features in one bundle.
This section provides a high-level overview and information to begin developing your bundles for the Nexus platform, specifically the Nexus Repository.
Knowledge of Apache Maven and Java is required for your bundle development efforts. OSGi-related knowledge is highly relevant and beneficial. Please ensure to consult the documentation for the relevant projects, when necessary.
Bundles for Nexus Repository are written in Java as the implementation language using Apache Maven as the build system. The public code base may used as a starting point to investigate existing bundles and their source code.
The easiest way to create a new bundle project is to replicate a bundle with a similar functionality. Inspect the source code of bundles with similar functionality, and read the JavaDoc documentation for the involved classes.
To gain access to all the components needed for your bundle development, you have to proxy the Sonatype grid repository with the URL:
https://repository.sonatype.org/content/groups/sonatype-public-grid/
Set up your project to include inheriting from the parent of all the Nexus Repository bundles with the version you are targeting as follows.
<parent>
<groupId>org.sonatype.nexus.plugins</groupId>
<artifactId>nexus-plugins</artifactId>
<version>3.0.0-SNAPSHOT</version>
</parent>Use the identical version of the parent as the Nexus Repository instance on which you want to run your bundle. When developing a bundle you are using large parts of the internal implementation, which are subject to change from one version to another.
This same logic applies to all dependencies as well.
A bundle Maven project creates a custom-built output file in the form of an OSGi bundle. Enable this by changing the packaging to bundle. In addition, you need to add the karaf-maven-plugin and any needed dependencies. Inspect the pom.xml files for specific bundles in the plugins directory for further details.
These dependencies pull in a large number of transitive dependencies that expose Nexus Repository functionality and other libraries to your project. Depending on the type of bundle and functionality you aim to create, additional dependencies and other details can be added to this minimal project setup. A large number of further classes are available and can be used as part of your bundle development.
Except for interfaces and code that are required to be accessible from modules outside of the format bundle, all code should be nested within an internal directory that will be isolated by the OSGi run-time container.
Once you have created your Maven project as described above, you can build the bundle with the following command
mvn clean install
The Nexus Repository Manager application runs on the OSGi container Apache Felix. All features and plugins are managed by the container and are implemented as OSGi bundles. The Bundles feature view is available in the System section of the Administration main menu. It allows you to inspect a list of all the OSGi bundles that are deployed as part of the application and access detailed information about each bundle.
Find out more about OSGi and OSGi bundles on the website of the OSGi Alliance.
Permission to access this page in your Nexus Repository Manager can be granted granularly using the nx-bundles privilege.
To include your bundle in Nexus Repository, the bundle needs to be loaded by the OSGi container.
The default build assembles multiple bundles that form the foundation of Nexus Repository. These definitions are found in the assemblies module. The supported distributions are defined in the modules nexus-oss-feature and nexus-pro-feature, which are part of the internal code base.
If the plugin bundle has been built as a KAR file you can just drop the file into $install-dir/deploy and it will be automatically unpacked and deployed. KAR files are like the old “plugin bundles” in Nexus Repo 2, they contain the plugin jar as well as its dependencies and a feature file that describes the plugin.
Assuming the plugin project uses org.sonatype.nexus.plugins:nexus-plugins as its parent then you can use the buildKar Maven profile when building the plugin to make a deployable KAR file.
mvn -PbuildKar clean install
Note that KAR file support was added in version 3.15.0 of Nexus Repository.
If you're using a Nexus Repository 3.14.0 or earlier, or the plugin is not available in KAR format, use this procedure.
An installation of the repository manager defines the feature it loads in $data-dir/etc/nexus.properties and additional features can be declared to be loaded there. E.g. to add my-custom-feature to a Nexus Repository installation change to:
nexus-features=nexus-oss-feature,my-custom-feature
The feature my-custom-feature is a Maven project that includes the desired bundles as dependencies. Alternatively, add a specific feature via Karaf commands.
Bundles can be loaded via the Karaf console. To enable the console, set karaf.startLocalConsole in bin/nexus.vmoptions to true. This allows you to access the Karaf console by pressing enter after starting the repository manager with the run option.
The bundle:install command can be used to load a bundle into the container.
For development usage, you can set the local Maven repository as the source for any bundle loading with e.g.
config:property-set -p org.ops4j.pax.url.mvn
org.ops4j.pax.url.mvn.defaultRepositories "file:${user.home}/.m2/repository@id=system.repository@snapshots"Once your bundle is installed, it will be displayed as part of the output from bundle:list. With the local Maven repository configured as a source, you can rebuild your bundle and get it reloaded and the repository completed restarted with:
bundle:update 270 bundle:refresh system:shutdown -f -r
This process ensures that bundles are updated, imports are correctly picking up any changes and the full repository manager runs through the full start-up life-cycle.
Ideally, any new bundles created yield significant benefits for the overall community of users. Sonatype encourages the contribution of such bundles to the upstream repository and is offering support and help for such efforts.
The minimum steps for such contributions are:
Create a pull request with the relevant changes to the nexus-public repository
Sign and submit a contributor license agreement to Sonatype
In further collaboration, Sontaype will decide upon the next steps on a case-by-case basis and work with you to:
Create sufficient tests
Provide access to upstream repositories
Facilitate other infrastructure such as CI server builds
Help you with verification and testing
Work with you on user documentation and outreach
Expose your work to the user community