Automated deployment with Cargo and Maven - a short primer

Tuesday, 29 December 2009 07:18

Cargo is a versatile library that lets you manage, and deploy applications to, a variety of application servers. In this article, we look at how to use Cargo with Maven.

If you are starting from scratch, you can use an Archetype to create a Cargo-enabled web application:

mvn archetype:create -DarchetypeGroupId=org.codehaus.cargo 
-DarchetypeArtifactId=cargo-archetype-webapp-single-module 
-DgroupId=com.wakaleo -DartifactId=ezbank

Or it is easy to add to an existing configuration - just add the cargo-maven2-plugin to your pom file.

The default configuration will deploy the application to an embedded Jetty server:

<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <version>1.0</version>
</plugin>

Then just run mvn cargo:start.

However Cargo is designed for deployment, and does not support rapid lifecycle development - use the ordinary Jetty plugin for that.

Deploying to a Tomcat instance

You can run your integration tests against a Tomcat server that Cargo will initialize and configure for the occasion - this is referred to as 'standalone' mode:

<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <version>1.0</version>
  <configuration>
    <!-- Container configuration -->
    <container>
      <containerId>tomcat6x</containerId>
      <home>/usr/local/apache-tomcat-6.0.18</home>
    </container>
    <configuration>
      <type>standalone</type>
      <home>target/tomcat6x</home>
    </configuration>
  </configuration>
</plugin>

Cargo will create a base directory (think CATALINA_BASE) in a directory that you specify. It will use the Tomcat home directory that you provide. At each installation, Cargo will destroy and recreate the base directory.

You can also download and install a Tomcat installation as required using the element:

<zipUrlInstaller>
  <url>http://www.orionserver.com/distributions/orion2.0.5.zip</url>
  <installDir>${java.io.tmpdir}/cargoinstalls</installDir>
</zipUrlInstaller>

This is a more portable solution which is useful for integration tests

Running integration tests with Cargo

You can use Cargo to automatically start up a web server to run your integration tests. This means you can run your integration tests on any of the supported servers (Tomcat, Jetty, JBoss, Weblogic,...):

<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <version>1.0</version>
  <executions>
    <execution>
      <id>start-container</id>
      <phase>pre-integration-test</phase>
      <goals>
        <goal>start</goal>
      </goals>
    </execution>
    <execution>
      <id>stop-container</id>
      <phase>post-integration-test</phase>
      <goals>
        <goal>stop</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <wait>false</wait>      
    <!-- Container configuration -->
    <container>
      <containerId>tomcat6x</containerId>
      <home>/usr/local/apache-tomcat-6.0.18</home>
    </container>
    <configuration>
      <type>standalone</type>
      <home>target/tomcat6x</home>
    </configuration>
  </configuration>
</plugin>

Deploying to an existing server

You can also deploy to a running application server. You need to use the 'existing' configuration type (existing). You can use a separate profile to run the integration tests in a standalone instance and then deploy to a running instance.

<profiles>
  <profile>
    <id>integration</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.codehaus.cargo</groupId>
          <artifactId>cargo-maven2-plugin</artifactId>
          <version>1.0</version>
          <configuration>
            <!-- Container configuration -->
            <container>
              <containerId>tomcat6x</containerId>
            </container>
            <configuration>
              <type>existing</type>
              <home>/usr/local/apache-tomcat-6.0.18</home>
            </configuration>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>
...

Then you can deploy your application as shown here:

$ mvn install

$ mvn cargo:deploy -Pintegration

Deploying to a remote server

You can also deploy to a remote server, using the server-specific remote API (e.g. the HTML manager application for Tomcat). You need to set up a container of type 'remote' and a configuration of type 'runtime':

<configuration>
  <!-- Container configuration -->
  <container>
    <containerId>tomcat6x</containerId>
    <type>remote</type>
  </container>
  <configuration>          
    <type>runtime</type>
    <properties>
      <cargo.remote.username>admin</cargo.remote.username>
      <cargo.remote.password></cargo.remote.password>
      <cargo.tomcat.manager.url>http://localhost:8888/manager</cargo.tomcat.manager.url>
    </properties>
  </configuration>
  ...
</configuration>

In the <properties> section, you define server-specific properties (see the Cargo documentation). Then you use Cargo as usual:

$ mvn cargo:redeploy -o 
...
[INFO] [cargo:redeploy]
[INFO] [mcat6xRemoteDeployer] Redeploying [/Users/johnsmart/.m2/repository/org/ebank/
ebank-web/1.0.0-SNAPSHOT/ebank-web-1.0.0-SNAPSHOT.war]
[INFO] [mcat6xRemoteDeployer] Undeploying [/Users/johnsmart/.m2/repository/org/ebank/
ebank-web/1.0.0-SNAPSHOT/ebank-web-1.0.0-SNAPSHOT.war]
[INFO] [mcat6xRemoteDeployer] Deploying [/Users/johnsmart/.m2/repository/org/ebank/
ebank-web/1.0.0-SNAPSHOT/ebank-web-1.0.0-SNAPSHOT.war]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4 seconds
[INFO] Finished at: Fri Jul 17 17:45:34 CEST 2009
[INFO] Final Memory: 6M/12M
[INFO] ------------------------------------------------------------------------

Using a dedicated deployer module

You can dissociate the build process from the application deployment process by creating a separate Maven module dedicated to deployments. This also makes it easier to build and deploy your WAR file to Nexus on one server, and then deploy to your application server directly on the target machine.

To do this, you create a dedicated Maven module. It only needs to contain the Cargo plugin and a dependency on the application to be deployed. The Cargo plugin uses the section to obtain the WAR file to be deployed from your Nexus repository.

<project>
...
<build>
  <plugins>
    <plugin>
      <groupId>org.codehaus.cargo</groupId>
      <artifactId>cargo-maven2-plugin</artifactId>
      <version>1.0</version>
      <configuration>
        <!-- Container configuration -->
        <container>
          <containerId>tomcat6x</containerId>
        </container>
        <configuration>
          <type>existing</type>
          <home>/usr/local/apache-tomcat-6.0.18</home>
        </configuration>
        <deployer>
          <deployables>
            <deployable>
              <artifactId>ebank-web</artifactId>
              <groupId>org.ebank</groupId>
              <type>war</type>
            </deployable>
          </deployables>
        </deployer>
      </configuration>
    </plugin>
  </plugins>
</build>

The dependencies section contains a reference to the WAR file to be deployed. You can use a property here so that you can pass a version number from the command line:

    ...
  <dependencies>
    <dependency>
      <groupId>org.ebank</groupId>
      <artifactId>ebank-web</artifactId>
      <type>war</type>
      <version>${target.version}</version>
    </dependency>
  </dependencies>  
  
  <properties>
    <target.version>${project.version}</target.version>
  </properties>