Run and Develop with Cargo

Introduction

Goal

Use Cargo to run your Bloomreach Content implementation project in your development environment.

What is Cargo

Cargo is a tool that provides a standard interface for controlling Java EE containers. In development environments, use Cargo to run both the CMS and HST applications within a single container, managed by Maven. The standard Maven POM included with the archetype comes pre-configured with the Maven Cargo plugin for Tomcat 9. This page describes how to use the default Cargo setup: running, debugging, and customizing the configuration.

Run with Cargo

To run a Bloomreach Content project—which includes a CMS instance with an embedded JCR repository and an HST website—a dedicated Maven profile for Cargo is provided by the Bloomreach Content Project POM. This POM serves as the base for all Bloomreach Content projects, including both core CMS modules and end-user projects. You can review the Project POM and its Cargo configuration in the Bloomreach Content Maven repository. For information about Maven profiles, see the introduction to build profiles in the Maven documentation.

Activate Maven profiles using the -P switch. To run a Bloomreach Content project with Cargo, execute the following command from your project root:

mvn -P cargo.run

You must run this command from the root directory of your project. On the first run, this command downloads a Tomcat 9 distribution, unpacks it to target/cargo/installs/apache-tomcat-9.x.xx, and copies it to target/tomcat9x, updating some Tomcat configuration files. Cargo then starts Tomcat from target/tomcat9x. Before startup, Cargo copies your project's web applications and required shared libraries into the Tomcat installation: web applications go to target/tomcat9x/webapps, and shared libraries go to target/tomcat9x/shared/lib.

Debug with Cargo

The Bloomreach Content Cargo profile enables debugging on port 8000 by default. You can attach a debugger without additional configuration. For details on using Eclipse's debugger, see Develop with Eclipse.

By default, Cargo starts Tomcat without waiting for a debugger to attach. To make the JVM wait for a debugger before starting, set the cargo.debug.suspend property:

mvn -P cargo.run -Dcargo.debug.suspend=y

Use this option to debug issues during CMS or website startup and initialization. The JVM will suspend execution until a debugger is attached.

To use a different debugging port, set the cargo.debug.address property:

mvn -P cargo.run -Dcargo.debug.address=9000

If you need a faster development cycle, see Using JRebel to develop your project.

Run with Cargo without Development Repository Data

Info: This feature is available in the Bloomreach Content Maven archetype version 4.0.1 and later.

A standard Bloomreach Content project created from the Maven archetype includes repository data JAR modules: repository-data-development and repository-data-site-development. By default, these JARs are deployed to Tomcat's shared/lib directory. To omit these modules, activate the without-development-data Maven profile along with cargo.run:

mvn -P cargo.run,without-development-data

This command prevents deployment of the repository-data-development and repository-data-site-development JARs. Use this setup when you want to test an upgraded project locally with a copy of an existing production repository.

Run with Cargo using Different Port Numbers

By default, the Cargo plugin configures connectors on standard ports: 8080 for HTTP, 8025 for RMI, and optionally 8009 for AJP.

To change these ports, add properties to the Cargo profile configuration. For example:

<profile>
  <id>cargo.run</id>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.cargo</groupId>
        <artifactId>cargo-maven3-plugin</artifactId>
        <configuration>
          <!-- SNIP -->
          <configuration>
            <properties>
              <!-- SNIP -->
              <cargo.servlet.port>9080</cargo.servlet.port>
              <cargo.rmi.port>9205</cargo.rmi.port>
              <cargo.tomcat.ajp.port>9009</cargo.tomcat.ajp.port>
              <!-- SNIP -->
            </properties>
          </configuration>
          <!-- SNIP -->
        </configuration>
        <!-- SNIP -->
      </plugin>
    </plugins>
  </build>
</profile>

This configuration sets the HTTP connector to port 9080, the RMI port to 9205, and the AJP port to 9009.

You can also specify a debug address when running Cargo:

mvn -P cargo.run -Dcargo.debug.address=9000

To override all Cargo JVM arguments, including the debug address, add the following property:

            <properties>
              <!-- SNIP -->
              <cargo.jvmargs>-agentlib:jdwp=transport=dt_socket,address=9000,server=y,suspend=${cargo.debug.suspend} -noverify ${javaagent} ${cargo.jvm.args}</cargo.jvmargs>
              <!-- SNIP -->
            </properties>

After updating the configuration, run Cargo as usual:

mvn -P cargo.run

If you change the HTTP port, update the delivery tier configuration in the Console to match the new port:

/hst:hst/hst:hosts/dev-localhost
  - hst:defaultport = 9080

Pass System Properties

To pass system properties to your application in a Cargo-based development environment, use one of these methods:

Option 1: Add properties to the Cargo plugin configuration in your main POM:

    <profile>
      <id>cargo.run</id>
      <build>
        <plugins>
          <plugin>
            <groupId>org.codehaus.cargo</groupId>
            <artifactId>cargo-maven3-plugin</artifactId>
            <configuration>
              <container>
                <systemProperties>
                  <repo.config>
                     file:${project.basedir}/conf/repository.xml
                  </repo.config>

Option 2: Pass properties on the command line using -Dcargo.jvm.args:

mvn -Pcargo.run -Dcargo.jvm.args="-Drepo.path=./storage"

Customize the Cargo Profile

The Cargo profile is defined in the Bloomreach Content Project POM. If you created your project using the archetype, your root POM inherits from the Bloomreach Content Release POM, not directly from the Project POM. The Release POM specifies all Bloomreach Content artifacts and their versions for a given release, and extends the Cargo profile. Artifacts intended for Tomcat's shared library location are defined in the Release POM. You can find the Release POM version your project uses here.

Your project's root POM further extends the Cargo profile, specifying the two WAR files to be deployed by Cargo. The effective Cargo profile is the result of merging the Project POM, Release POM, and your root POM. Note that the mvn help:effective-pom goal does not accurately display the merged profile configuration.

You may need to modify the Cargo profile in certain cases, such as deploying an additional web application or loading a JAR artifact with Tomcat's shared classloader.

  • To deploy another web application:
    Add an additional deployable configuration to the existing deployables section.

  • To load a shared JAR artifact:
    If you have code that must be accessible by multiple web applications (for example, to enable inter-application communication), add the JAR as a shared dependency in the Cargo profile. There are two scenarios:

    1. The shared artifact is an external dependency.
    2. The shared artifact is produced by a submodule.

For example, to load both types of shared artifacts:

<profile>
  <id>cargo.run</id>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.cargo</groupId>
        <artifactId>cargo-maven3-plugin</artifactId>
        <configuration>
          <container>
            <dependencies>
              <!-- External shared dependency: must be declared as a project dependency with 'provided' scope -->
              <dependency>
                <groupId>org.example</groupId>
                <artifactId>mysharedartifact</artifactId>
                <classpath>shared</classpath>
              </dependency>
              <!-- Submodule artifact: reference the built JAR directly -->
              <dependency>
                <location>
                  ${project.basedir}/shared/target/shared-${project.version}.jar
                </location>
                <classpath>shared</classpath>
              </dependency>
            </dependencies>
          </container>
          <!-- SNIP -->
        </configuration>
      </plugin>
    </plugins>
  </build>
</profile>

For external dependencies, declare them in your project's dependencies with provided scope. This prevents the artifact from being packaged in subproject WARs, ensuring it is loaded by the shared classloader.

For submodule artifacts, reference the built JAR directly using the <location> element. This approach avoids circular dependencies.

If you need a dependency to be loaded by the container-wide common classloader (for example, to provide a JDBC driver for Tomcat's JNDI DataSource), use the extra classpath:

<classpath>extra</classpath>
Share Feedback
Page: /build/development-tools/run-and-develop-with-cargo
Section: Build
Category *