Capistrano SCM Maven

A Capistrano SCM plugin is supposed to be a client of a proper Source Control system, right? Well, what if you're working in a compiled language and your source has already been versioned and a compiled artifact made from it? That's where this plugin comes in. It complies with the interface of an SCM plugin (pretty well, I think) but the "repo" is a tarball that contains your application.

I chose Maven for the name because it is the artifact repository standard that Maven created (and Artifactory and Nexus both implement). I doesn't refer to building Java source with the Maven's mvn tool. Thanks to jmpage's Capistrano SCM Nexus plugin for ideas and reference, which in some cases resulted in outright theivery.

Background

My team is made up of Java developers and Ruby developers. Looking over the fence from the Java side of things, I was jealous of the Ruby team's ability to use Capistrano - a great automated deployment tool. Some of our Java projects use Python's Fabric which is very nice but it's the only python tool we use. So, in the interest of standardizing on one tool, especially with an eye for automating deploys in a similar way in a Gitlab pipeline, I decided to see if Capistrano would work for Java deployments.

Notes

(differences from other SCM plugins)

Because we're deploying a binary tarball, the directory structure within the artifact is important. In short, it needs to match the final expanded directory structure to work. I call this structure the maven_artifact_style and default it to 'cap'. For Java projects, this means that the executable jar within the tarball should not have the version on it so scripts and/or systemd can find it consistently. In fact nothing in the tarball should be versioned. This doesn't cause version confusion because the tarball is versioned and the extracted version of the executable jar will already be contained within a specific release in the normal Capistrano releases directory. I discuss below how to use Maven's Assembly plugin to create a tarball artifact compliant with this gem.
When I refer to the term repo in this documentation, I mean the artifact repository. But in the plugin framework code, repo means the artifact contents.

Features

Supports separate release and snapshot repositories. This is needed in Artifactory (I don't know anything about Nexus but supposedly should be useful there too).
Downloads the artifact from repo only if archive is a snapshot or is a release and not present already
Supports non-standard repo ports
Supports 302 redirects from the repo

Install

Install the gem manually:

gem install capistrano-scm-maven

or add it to your Gemfile when using Bundler:

gem 'capistrano-scm-maven'

Configure

Require the gem in your Capfile:

require 'capistrano_scm_maven'

Configure the gem's variables

set :maven_endpoint, 'http://agoodno.com:8081/artifactory'
set :maven_repository, 'libs-snapshot'
set :maven_group_id, 'com.agoodno'
set :maven_artifact_version, '0.0.1-SNAPSHOT'
set :maven_artifact_name, 'sample'
set :maven_artifact_style, 'cap'
set :maven_artifact_ext, 'tar.gz'

The configuration above would result in an attempt to retrieve the artfact at:

`http://agoodno.com:8081/artifactory/libs-snapshot/com/agoodno/sample/0.0.1-SNAPSHOT/sample-0.0.1-SNAPSHOT-cap.tar.gz`

Build Artifact

Add assembly plugin

Add Maven's Assembly Plugin to your Maven POM file.

pom.xml

  ...
  <build>
    <plugins>
      ...
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>3.1.0</version>
        <configuration>
          <descriptors>
            <descriptor>src/assembly/cap.xml</descriptor>
          </descriptors>
        </configuration>
        <executions>
          <execution>
            <id>make-assembly</id>
            <phase>package</phase>
            <goals>
              <goal>single</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...

Create the assembly file

The assembly file referenced in the POM above describes how to build the tarball with your application's final directory structure. Setting includeBaseDirectory to false below removes the versioned container directory that is created by default. Also, destName is set to remove the version from the aplication jar. I've only added a README.md in addition to the application jar. See the Assembly plugin's documentation to build out your application's whole structure.

src/assembly/cap.xml

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
  <id>cap</id>
  <formats>
    <format>tar.gz</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <files>
    <file>
      <source>target/${artifactId}-${version}.${packaging}</source>
      <destName>${artifactId}.${packaging}</destName>
    </file>
    <file>
      <source>README.md</source>
    </file>
  </files>
</assembly>

Verify

You can verify that the gem is installed by listing the tasks available to capistrano with:

cap -T

You should see 3 maven namespaced commands in the list.

Run

Because this gem takes part in the normal capistrano deploy lifecycle, to run it just run the deploy task as you normally would:

cap staging deploy

adamkrone/capistrano-scm-maven