Saturday, July 9, 2016

How to deploy your project to Maven Central

So, you have finally got your project finialized, tested, and ready to go. You would probably want to make it available to users through their build system (Maven, Gradle,..). This post presents steps that you need to take to deploy your project to Maven Central.

1) Create a ticket in Sonatype for the creation of your Group ID:

  This can be done by creating an issue in Sonatype's tracker : https://issues.sonatype.org/. You usually get a response within one day.


2) Get your project ready to deploy:

   Before deploying your project, you need to make sure that your pom.xml contains a number of elements: project name, description, URL, license information, developer information, and SCM information. If you do not include these elements, your pom file will not be validated and you will not be able to deploy to Maven Central.

Here is a pom example: https://github.com/gwidgets/gwty-leaflet/blob/master/pom.xml

3) Snapshot Vs non snapshot :

If your release is a snapshot version, you need to include Sonatype's snapshots server. On deploy, Maven automatically detects if your version ends with -SNAPSHOT and deploys to the snapshot server.

<distributionManagement>
  <snapshotRepository>
    <id>ossrh</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
  </snapshotRepository>
</distributionManagement>


4) Generating Javadocs and including sources:

Including javadocs and sources is also mandatory, and checked by Sonatype at release time. There are several ways you can do it, but the easiest way is to include Maven javadocs and sources plugins which automatically generates them for you on build time.

Maven javadoc plugin : https://maven.apache.org/plugins/maven-javadoc-plugin/
Maven source plugin:  https://maven.apache.org/plugins/maven-source-plugin/

5) Sign your jar and pom:

This is the trickiest part. To be able to successfully release your project to Maven central, you need to generate a signature using GPG which will be used by Sonatype to verify your articacts. First of all, you will need to install GPG. The next step is to generate a public/private key pair. This step is descibed in more details in GPG's manual. Aftewards, you need to distribute your public key to a key server. We use https://pgp.mit.edu/ which allows you to directly copy paste the key. There are plenty of servers, it's a matter of preference. You can refer once again to the manual for how to send your keys to the server. Once done, you can sign your artifacts, you will have to sign both the jar and the pom. You can either do it manually from the termnial using gpg or using maven gpg plugin: http://maven.apache.org/plugins/maven-gpg-plugin/

6) Prepare your deploy:

Before deploying you will need to configure the server and its access information:
<distributionManagement>
  <snapshotRepository>
    <id>ossrh</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
  </snapshotRepository>
  <repository>
    <id>ossrh</id>
    <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
  </repository>
</distributionManagement>

<settings>
  <servers>
    <server>
      <id>ossrh</id>
      <username>your-id</username>
      <password>your-pwd</password>
    </server>
  </servers>
</settings>

It's better to include these information in a build profile, so that they are not shared if you ever make your project source code open to public, and also to be able to reuse them for other projects.
It's also a good practice to include maven's source, javadocs, and gpg plugins in a build profile, to avoid having to include them in each project.

7) Deploy to staging:

deploying to staging can simply be done by invoking Maven's deploy goal:

mvn deploy

8) Relase your project to Maven Central:

At this stage, you will able to find your project on Sonatype. You need to go to https://oss.sonatype.org/ and click on staging repositories. After choosing your repository, you need to click on --> close, as shown below. Once the repository is closed, you can click on release and your project will be released to Maven Central.