Maven Repository
Cloudsmith provides public & private repositories for Maven
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 artifacts
If using Gradle - please see our Gradle documentation
If using sbt - please see our sbt documentation
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/rsa-key pre-configured).
In the following examples:
| Identifier | Description |
|---|---|
| OWNER | Your Cloudsmith account name or organization name (namespace) |
| REPOSITORY | Your Cloudsmith Repository name (also called "slug") |
| TOKEN | Your Cloudsmith Entitlement Token (see Entitlements for more details) |
| USERNAME | Your Cloudsmith username |
| PASSWORD | Your Cloudsmith password |
| API-KEY | Your Cloudsmith API Key |
| PACKAGE_VERSION | The semantic version number of your package |
| GROUP_ID | A unique Maven identifier for your project across all projects and usually takes the form of a reverse domain i.e "com.companyname" |
| ARTIFACT_ID | The name of the jar without version i.e "project" |
Upload a Package
To upload, you need to generate your package first. You can do this with:
mvn package
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.
What is a POM?
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.
What is a Fat Jar?
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.
Upload via Maven
The endpoint for the native Maven API is:
https://maven.cloudsmith.io/OWNER/REPOSITORY/
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 pom.xml file:
<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:
mvn deploy
You can find out more about Maven publishing in the official Maven documentation.
Upload via the Cloudsmith CLI
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
Example:
cloudsmith push maven org/repo validation-api-1.0.0.GA.jar --pom-file=validation-api-1.0.0.GA.pom
Upload via Cloudsmith Website
Please see Upload a Package for details of how to upload via the Website UI.
Example Project
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!
Download / Install a Package
Setup
To enable the retrieval of Cloudsmith hosted packages via Maven, the first step is to add your repository to the dependencyManagement section of your pom.xml file.
To do this add one of the following XML examples to your project pom.xml file:
Public Repositories
<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 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.
Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code or expose them in any logs
<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).
Specifying Dependencies
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 pom.xml file:
<dependency>
<groupId>GROUP_ID</groupId>
<artifactId>ARTIFACT_ID</artifactId>
<version>PACKAGE_VERSION</version>
</dependency>
Install a Package
To download all the dependencies specified in your pom.xml file and build your project you just need to run:
mvn install
Security Scanning
Supported
Please see our Security Scanning documentation for further information.
Upstream Proxying / Caching
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.
Key Signing Support
GPG Index Packages
Troubleshooting
Please see the Troubleshooting Maven page for further help and information.
Updated 4 months ago
