# Codehaus Cargo : Maven 3 Plugin

Created by Former user, last modified by S. Ali Tokmen on Jan 15, 2022
A Maven 3 plugin that wraps the Cargo Java API. Though there are no minimum version requirements, all building, continous testing and release activities are performed using Maven 3.2.5 and onwards so we would recommend you have that installed.

Functional tests

The usage of Cargo for executing functional tests on a container does not mandate this Maven plugin. You could also directly use the Cargo Java API from your Java unit test classes (JUnit, TestNG, etc), as described on the Functional testing page. The choice is yours, though the Maven plugin is generally more straightforward to use and integrates better with the whole build process (with profiles, easier to use deployer, proxy server support, etc.)

Reg. Lifetime of our Maven 2 plugin

Please be aware that the Maven 2 / Maven 3 plugin of Codehaus Cargo has been retired with our version 1.9.0 and has been superseded by a Maven 3 only plugin.

# Table of Contents

The documentation for this Maven plugin includes:

- Installation: explains how to install the plugin
- Getting started: explains how to use the plugin on several use cases
- Reference Guide: provide reference documentation for all configuration options
- Tips: tips for using the plugin

# 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
        -Dcargo.maven.containerId=tomcat9x

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
        -Dcargo.maven.containerId=tomcat9x
        -Dcargo.maven.containerUrl=https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/9.0.45/tomcat-9.0.45.zip

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
        -Dcargo.maven.containerId=wildfly20x
        -Dcargo.maven.containerUrl=https://download.jboss.org/wildfly/20.0.1.Final/wildfly-20.0.1.Final.zip
        -Dcargo.servlet.port=9000

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:

- Generating a container configuration deployment structure
- Starting and stopping a container
- Merging WAR files
- Deploying to a running container

## The Cargo Maven plugin in detail

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

Goals | Description
--- | ---
`cargo:start` | Start a container. That goal will: If the plugin configuration requires so, installs the container. If the plugin configuration defines a container with a standalone local configuration, it will create the configuration. If the plugin configuration contains one or more deployables, it will deploy these to the container automatically. If the plugin configuration contains no deployables but the project's packaging is J2EE, Java EE or Jakarta EE (WAR, EAR, etc.), it will deploy the project's deployable to to the container automatically. And, of course, start the container. 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`.
`cargo:run` | Start a container and wait for the user to press `CTRL + C` to stop. That goal will: If the plugin configuration requires so, installs the container. If the plugin configuration defines a container with a standalone local configuration, it will create the configuration. If the plugin configuration contains one or more deployables, it will deploy these to the container automatically. If the plugin configuration contains no deployables but the project's packaging is J2EE, Java EE or Jakarta EE (WAR, EAR, etc.), it will deploy the project's deployable to to the container automatically. And, of course, start the container and wait for the user to press `CTRL + C` to stop.
`cargo:stop` | Stop a container.
`cargo:restart` | Stop and start again a container. If the container was not running before calling `cargo:restart`, it will simply be started.
`cargo:configure` | 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.
`cargo:package` | Package the local container.
`cargo:daemon-start` | 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.
`cargo:deployer-start` | Start a deployable already installed in a running container.
`cargo:deployer-stop` | 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.
`cargo:uberwar` | Merge several WAR files into one.
`cargo:install` | 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`.
`cargo:help` | Get help (list of available goals, available options, etc.).

The configuration elements are described in the Reference Guide section.