Maven is a build automation tool primarily associated with the Java programming language. Developed by the Apache Software Foundation and released in 2004 it provides a standardized way to describe how a software project is built.
A Maven Repository or Maven Repo is a registry of packaged files, stored, indexed, and made accessible to projects that depend on them. Each package has a unique name and version allowing for repeatable continuous integration and continuous delivery (or continuous deployment) tasks.
The Maven repository index stores metadata about each package; that the Maven tooling looks up at build time enabling pulling in of dependency projects and extensions.
For more information on Maven, please see:
- Maven: The official website for Apache Maven
- Maven Central: Popular public repository for Maven artefacts
The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy n' paste snippets (with your namespace/repo pre-configured).
In the following examples:
Your Cloudsmith account name or organisation name (namespace)
Your Cloudsmith Repository name (also called "slug")
Your Cloudsmith Entitlement Token (see Entitlements for more details)
Your Cloudsmith username
Your Cloudsmith password
Your Cloudsmith API Key
The semantic version number of your package
A unique Maven identifier for your project across all projects and usually takes the form of a reverse domain i.e "com.companyname"
The name of the jar without version i.e "project"
To upload, you need to generate your package first. You can do this with:
This generates a Maven package file (
.jar or similar) like
your-package-1.2.3.jar that you can upload.
You will always need at least the package file and the POM file for uploading.
A POM, the Project Object Model, is the XML file that describes all the aspects of your project that relate to building and packaging the source code into a package file. Typically a jar (java archive). The metadata held within the pom.xml that is typically stored within the jar itself allows Maven to index the package into a Maven Repository for easy distribution.
A Fat Jar, is also referred to as an Uber Jar, is a Java Archive library that contains all classes, including all the classes of its dependencies. This allows the Jar to be run standalone without requiring any further code available on the Class Path.
The disadvantage of creating an all-in-one jar mean that you have to deploy everything (a potentially large file) each time. If you split the Fat Jar into components you can separately test, version and release code enabling faster deployments and your developers to cherry-pick components for inclusion in other projects.
The endpoint for the native Maven API is:
The distribution repositories define where to push your artifacts. In this case it will be a single repository, but you can configure alternatives. Add the following to your project
<distributionManagement> <snapshotRepository> <id>NAME</id> <url>https://maven.cloudsmith.io/OWNER/REPOSITORY/</url> </snapshotRepository> <repository> <id>NAME</id> <url>https://maven.cloudsmith.io/OWNER/REPOSITORY/</url> </repository> </distributionManagement>
You can configure different repositories for snapshots and releases, and you can replace NAME with your own identifier(s) (but make sure they match settings elsewhere).
You then can configure your
~/.m2/settings.xml file with the API key of the uploading user:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> <servers> <server> <id>NAME</id> <username>USERNAME</username> <password>API-KEY</password> </server> </servers> </settings>
You can now publish to the native API with:
You can find out more about Maven publishing in the official Maven documentation.
The command to upload a Maven package via the Cloudsmith CLI is:
cloudsmith push maven OWNER/REPOSITORY ARTIFACT_ID-PACKAGE_VERSION.jar --pom-file=ARTIFACT_ID-PACKAGE_VERSION.pom
cloudsmith push maven org/repo validation-api-1.0.0.GA.jar --pom-file=validation-api-1.0.0.GA.pom
Please see Upload a Package for details of how to upload via the Website UI.
For examples of what your project should look like for packaging and publishing/uploading, please have a look at our examples repository (on GitHub). We'll supplement these with more detailed guidance later, but otherwise just ask, we're here to help!
To enable the retrieval of Cloudsmith hosted packages via Maven, the first step is to add your repository to the dependencyManagement section of your
To do this add one of the following XML examples to your project
<repositories> <repository> <id>NAME</id> <url>https://dl.cloudsmith.io/public/OWNER/REPOSITORY/maven/</url> <releases> <enabled>true</enabled> <updatePolicy>always</updatePolicy> </releases> <snapshots> <enabled>true</enabled> <updatePolicy>always</updatePolicy> </snapshots> </repository> </repositories>
Private Cloudsmith repositories require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication.
The setup method will differ depending on what authentication type you choose to use.
<repositories> <repository> <id>NAME</id> <url>https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/maven/</url> <releases> <enabled>true</enabled> <updatePolicy>always</updatePolicy> </releases> <snapshots> <enabled>true</enabled> <updatePolicy>always</updatePolicy> </snapshots> </repository> </repositories>
<repositories> <repository> <id>NAME</id> <url>https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/maven/</url> <releases> <enabled>true</enabled> <updatePolicy>always</updatePolicy> </releases> <snapshots> <enabled>true</enabled> <updatePolicy>always</updatePolicy> </snapshots> </repository> </repositories>
If using HTTP Basic Authentication, you need to provide one following three types of credentials:
- Cloudsmith Username and Password
- Cloudsmith API Key
- An Entitlement Token
When using HTTP Basic Authentication you'll probably want to keep your credentials separately in your
settings.xml file instead of within the
pom.xml file. once you have decided which credentials you wish to use, setup your
settings.xml file as follows:
<settings> <servers> <server> <id>NAME</id> <username>USERNAME</username> <password>PASSWORD</password> </server> </servers> </settings>
<settings> <servers> <server> <id>NAME</id> <username>USERNAME</username> <password>API-KEY</password> </server> </servers> </settings>
<settings> <servers> <server> <id>NAME</id> <username>token</username> <password>TOKEN</password> </server> </servers> </settings>
We would highly advise that you encrypt your credentials using something like
mvn encrypt-password, of which you can refer to the mini encryption guide for more detailed help (external link).
For more details on authentication in Maven, please refer to the official Maven documentation (external link).
After the repository is added to the
pom.xml file, and credentials are added to the
settings.xml file (if using HTTP Basic Authentication), all that is left is to specify the dependency in the dependencies section of the project pom.xml file.
To do this add the following XML to your project
<dependency> <groupId>GROUP_ID</groupId> <artifactId>ARTIFACT_ID</artifactId> <version>PACKAGE_VERSION</version> </dependency>
To download all the dependencies specified in your
pom.xml file and build your project you just need to run:
Configurable Proxying Caching
You can configure upstream Maven repositories that you wish to use for packages that are not available in your Cloudsmith repository. In addition, you can also choose to cache any requested packages for future use.
Please see our Upstream Proxying documentation for further instructions.
GPG Index Packages
Please see the Troubleshooting Maven page for further help and information.
Updated 2 months ago