Automated deployment with Cargo and Maven - a short primer

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>

Tags See All Tags Add New Tag...

Please Enter New Tags Separated By Comma's
Or Close

Cargo

Maven

Bookmark

Email this

Trackback(0)

TrackBack URI for this entry

Comments (3) Add Comment

Subscribe to this comment's feed

Thanks
written by Karl Goldstein, February 23, 2010

Thanks, this was very helpful!

-1

F1
written by Aranya, April 20, 2010

Thanx for the sharing above. Just neeeded lil more info regarding
Deploying to a remote server. I am trying to deploy my grails project from hudson to a remote tomcat machine.So is it possible to restart the remote server using this cargo plugin ? Because if I do redeploy on the running machine, it always gets into PermgenSpace and outofmemory error.Thanx in advance.

Deploy to remote server
written by Mick, August 11, 2010

Hi,
I have the same needs as Aranya, can you explain in more detail how to deploy a WAR file from hudson to Tomcat6.x using cargo? Hudson has a plugin (which uses cargo as well) but it only supports upto v5.x and so I thought i could use cargo and give it a shot till the plugin gets upgraded.

Write comment

Learning Corner

Dr Dobb's Project of the Month: Thucydides

Results from large, automated runs of acceptance tests can be hard to understand quickly, especially for projects in active development. Learn how Thucydides synthesizes acceptance test results to present a visual overview of the project development status.

Upcoming courses

Testing and TDD for Java Developers in Melbourne
3 DAY WORKSHOP
Melbourne 2-4 April

Testing and TDD for Java Developers in Sydney
3 DAY WORKSHOP
Sydney - 26-28 March

Testing and TDD for Java Developers in Canberra
3 DAY WORKSHOP
Canberra - 1-3 May