Maven: How to Run

Introduction

This document covers the basic build-run-compile steps Jive recommends when using the Maven build. This assumes you've already looked at Maven: Start Here, How-To: Install Maven, and Maven: How To Create a New Maven Project .

Running Clearspace

Step 1: Make sure you have Apache Tomcat Installed

Download Tomcat 6.x and extract it (unzip) somewhere on your machine. We recommend C:\dev on Windows or ~/dev on OSX.

Step 2: Tell Maven where you put Tomcat

Point to the exploded Tomcat directory in your settings.xml You will find this in your local Maven repository.

On Windows:

C:\Documents and Settings\Your Name\.m2\settings.xml

Note also that you need to enable hidden directories in order to see your .m2 directory.

On OS X:

~/.m2/settings.xml

Then modify your settings.xml file here to point to your Tomcat installation:

. . .
 <profiles>
  <profile>
    . . .
          <properties>
            <tomcat6.home><![CDATA[/Users/gw/dev/apache-tomcat-6.0.16]]\></tomcat6.home>
        </properties>

Step 3: Configure your Plugins

If you want to include any plugins in your running instance, you need to include them in the command line when you run Tomcat. But first, the web/pom.xml needs to be set up to accept plugin inclusion. To do this, you need to make sure the Cargo plugin within the int profile by uncommenting the <pluginDirs> element, and ensuring a <jive.devMode> property exists with a value of true.

...
    <profiles>
        <profile>
            <id>int</id>
            ...
           <build>
                <plugins>
                    <plugin>
                        <groupId>org.codehaus.cargo</groupId>
                        <artifactId>cargo-maven2-plugin</artifactId>
                        <version>0.3-SNAPSHOT</version>
                        <configuration>
                            <wait>${cargo.wait}</wait>
                            <container>
                                <containerId>tomcat5x</containerId>
                                <home>${tomcat6.home}</home>
                                <systemProperties>
                                    <jiveHome>${basedir}/../target/jiveHome</jiveHome>
                                    <jive.ws.disabled>true</jive.ws.disabled>
                                    <jive.devMode>true</jive.devMode>
    <pluginDirs>${pluginDirs}</pluginDirs>
...

Step 4: Run Tomcat from Maven

Run this command from the web subdirectory under your custom project root. As described in Maven: How To Create a New Maven Project your custom project archetype creates your project root folder; the web directory hangs under that.

mvn -Dcargo.wait=true -P int integration-test

To debug just attach remote debugger to port 8787. Details on that are described in another document.

Variation: Faster Startup

With the standard execute command disabling web services via the following commandline option can improve startup time if they are not needed:

-Djive.ws.disabled=true

All together:

mvn -Dcargo.wait=true -Djive.ws.disabled=true -P int integration-test

This does the following:

Compile
Run unit tests
Package the war
Deploy the war to Tomcat
Start the Selenium Server
Startup Tomcat

That's works great for when you're developing against your web module. But what about when you're working on a plugin? It kind of sucks to have to build the plugin, then to have to re-build and re-deploy the webapp when there hasn't been any webapp changes.

So, here's an improvement:

mvn -Dcargo.wait=true -Djive.ws.disabled=true -P int cargo:start

This does the following:

Startup Tomcat w/ whatever deployables have been previously built

You can imagine that this reduces the build-time quite a bit.

Running Plugins

The way to run your plugins now (as of 2.5.3) is to pass the location of them into cargo from the commandline (or from the cargo script in the ./web/ directory.

For example, say your project has one plugin, "twitter". You would invoke cargo like so:

mvn -DpluginDirs=/path/to/twitter/target/twitter   -DskipTests=true -Dcargo.wait=true -P int integration-test

If you want to run multiple plugins, the value of pluginDirs may be comma-delimited.

If you're on 2.5.3 or below, or things aren't working, check the ./web/pom.xml to be sure that <pluginDirs>${pluginDirs}</pluginDirs> in the cargo configuration isn't commented out or missing. It would look like this:

<build>     <plugins>         <plugin>             <groupId>org.codehaus.cargo</groupId>             <artifactId>cargo-maven2-plugin</artifactId>             <version>0.3-SNAPSHOT</version>             <configuration>                 <wait>${cargo.wait}</wait>                 <container>                     <containerId>tomcat5x</containerId>                     <home>${tomcat6.home}</home>                         <systemProperties>                             <jiveHome>\${basedir}/../target/jiveHome</jiveHome>                             <jive.ws.disabled>true</jive.ws.disabled>                             <jive.devMode>true</jive.devMode>                             <pluginDirs>${pluginDirs}</pluginDirs>                         </systemProperties>

The compile-run step would be:

Compile your plugin from ./twitter/ with mvn install
Run the above command, making sure -DpluginDirs has been set.