Getting Started

Very quick start

Codehaus Cargo can be directly run on any existing Maven J2EE, Java EE or Jakarta EE project (WAR, EAR or other) by running:

mvn clean verify org.codehaus.cargo:cargo-maven3-plugin:run

This will create a default Jetty 9.x installed local container and start it using the Cargo Maven 3 plugin with your Maven 3 project's deployable (a WAR, for example) deployed to it; so you can run manual tests (as a first introduction).

What is magic is that if you now want to run the same tests with Tomcat 9.x you simply need to run (in one line):

mvn clean verify org.codehaus.cargo:cargo-maven3-plugin:run

That command will automatically:

  • Download the Maven artifact for the version of Tomcat 9.x that our Continous Integration has validated as working fine
  • Instantiate the container
  • Create a local configuration with your application
  • ... and, run it

To use a specific version of Tomcat 9.x, you simply need to run (in one line):

mvn clean verify org.codehaus.cargo:cargo-maven3-plugin:run

This time, the command will automatically download Tomcat 9.0.45 from the specified URL instead, taking into account any proxy server setting you would have in Maven 3, and will it in the default directory (see the Maven 3 Plugin Reference Guide for details), so it won't get downloaded when you run the same command twice.

If you now want to run this time on WildFly 20.x with with the HTTP port set to 9000, run:

mvn clean verify org.codehaus.cargo:cargo-maven3-plugin:run

As you can see, Codehaus Cargo's main advantage is that the commands and configuration remains the same for any version of any supported container - be it Tomcat, Jetty, JBoss, JOnAS, GlassFish, WebLogic, WildFly, etc.

Like it? Well, keep on reading, then!

More examples

As usual the best way to learn to use a tool is through examples.

We have several Maven 3 Archetypes that contain sample Maven 3 projects with different use cases for the Codehaus Cargo Maven 3 plugin, we would really recommend that you check them out. For more details, read here: Maven 3 Archetypes.

In addition here are the typical uses cases covered by the plugin:

The Cargo Maven plugin in detail

Here are the different goals available to call on this plugin:




Start a container. That goal will:

Note: A container that's started with cargo:start will automatically shut down as soon as the parent Maven instance quits (i.e., you see a BUILD SUCCESSFUL or BUILD FAILED message). If you want to start a container and perform manual testing, see our next goal cargo:run.


Start a container and wait for the user to press CTRL + C to stop. That goal will:


Stop a container.


Stop and start again a container. If the container was not running before calling cargo:restart, it will simply be started.


Create the configuration for a local container, without starting it.

Note: If the plugin configuration requires so, the cargo:start goal automatically installs the container.


Package the local container.


Start a container via the daemon. Read more on: Cargo Daemon

Note: The daemon:start goal is actually equivalent to a restart in Codehaus Cargo's terms; in the case a container with the same cargo.daemon.handleid already exists then it will be stopped first before your container is started. This also implies that in the case the new container fails to start, the old one will not be restarted.

cargo:daemon-stop Stop a container via the daemon. Read more on: Cargo Daemon

cargo:deployer-deploy (aliased to cargo:deploy)

Deploy a deployable to a running container.

Note: The cargo:start and cargo:run do already deploy the deployables specified in the configuration to the container; as a result calling cargo:deploy for a container which has been started by Codehaus Cargo in the same Maven project will most likely cause a second deployment of the same deployables (and might even fail).

cargo:deployer-undeploy (aliased to cargo:undeploy)

Undeploy a deployable from a running container.


Start a deployable already installed in a running container.


Stop a deployed deployable without undeploying it.

cargo:deployer-redeploy (aliased to cargo:redeploy)

Undeploy and deploy again a deployable. If the deployable was not deployed before calling cargo:deployer-redeploy (or its alias cargo:redeploy) it will simply be deployed.


Merge several WAR files into one.


Installs a container distribution, either downloaded using a URL or defined as a Maven artifact, on the file system.

Note: If the plugin configuration requires so, the cargo:start and cargo:run goals automatically install the container but will not call cargo:install.


Get help (list of available goals, available options, etc.).

The configuration elements are described in the Reference Guide section.

Copyright 2004-2024. All rights reserved unless otherwise noted.
Click here to read our privacy and cookie policy