• View
• Edit
• History
• Print

BuildWithMaven

CONGO + Maven quick start

If you're setting up a virgin command line environment and want to just check CONGO out of SVN, and build a war file, do these steps:

Procedure:

• Make sure you have all the DeveloperRequirements in place.
• Create a working development directory (i usually use 'work')
• Download Maven from http://maven.apache.org/ and unpack it as a subdirectory of 'work'
• Add the maven/bin/ dir to your path
• Check out a working copy of CONGO (this is the URL as of 7/9/2009) :
  • svn checkout http://svn.stonekeep.com/svn/congo/v2/trunk
• cd to the CONGO top level dir
• Tell Maven to rebuild the entire CONGO environment, including all dependencies:
  • mvn install (note this takes a while)
• If all goes well, you'll have a clean compile. The built war file is in the ./target/ subdir:
  dbs@shell:~/work/congo-2.0.0.2/target$ ls -l *.war
  -rw-r--r-- 1 dbs dbs 10604224 Jul 10 01:27 congo-2.0.0.2-SNAPSHOT.war
• Make sure you have an /opt/congo/congo/congo.properties file with the basics:
  

  database.autoupgrade=true 
   database.host=eventjdatastore.ck6kx2auo1hd.us-east-1.rds.amazonaws.com
   database.name=blah
   database.password=blah
   database.type=mysql
   database.user=blah

• Start up a jetty instance, running the new war file:
  mvn org.mortbay.jetty:maven-jetty-plugin:run
• (optionally) - a good thing to do is to supply a 'clean' target as well - that makes sure everything is really built from scratch:
  mvn org.mortbay.jetty:maven-jetty-plugin:run

Troubleshooting

• Under OSX, you need to directly specify which JVM version to use:
  export JAVA_VERSION=1.6

Alternate procedure to generate a snapshot war:

• mvn clean org.mortbay.jetty:maven-jetty-plugin:run-war

Alternate webrunner-invoked instance:

• java -Dpropertiesfile=someotherpropertyfile -Dcongo.jdbcurl=jdbc:mysql://localhost/yoinksandaway -jar target/dependency/webapp-runner.jar target/*.war

CONGO2? under eclipse (work in progress)

• for local use, replace 'mvn install' with 'mvn eclipse:eclipse; mvn install' for local, and set up eclipse

Releases:

• See Releases

Anything below this is from previous work on the build / dev process. Use with caution.

Quick start: run mvn package and pull the resulting WAR file from target/congo-VERSION.war.

Running CONGO 2 under Tomcat, from Maven

If you have a running Tomcat installation on your local machine, you can use maven to immediately deploy the created WAR to it. Add the following to ~/.m2/settings.xml:

<settings>
  <!-- ... -->

  <servers>
    <!-- ... -->

    <server>
      <id>congo.tomcat</id>
      <username>manager</username>
      <password>manager</password>
    </server>
  </servers>

  <!-- ... -->

  <profiles>
    <!-- ... -->

    <profile>
      <id>congo</id>
      <properties>
        <!-- Use the 'congo.tomcat' credentials for maven-tomcat-plugin -->
        <maven.tomcat.server>congo.tomcat</maven.tomcat.server>
        <!-- Redeploy if tomcat:deploy runs when the app is already deployed. -->
        <maven.tomcat.update>true</maven.tomcat.update>
      </properties>
    </profile>
  </profiles>

  <activeProfiles>
    <!-- ... -->
    <activeProfile>congo</activeProfile>
  </activeProfiles>

  <!-- ... -->
</settings>

(Replace the username and password with credentials that have access to Tomcat's /manager application, as appropriate.)

Then run mvn tomcat:deploy to deploy CONGO, or mvn tomcat:undeploy to remove CONGO from Tomcat.

For more information, see the plugin documentation for maven-tomcat-plugin.

Running CONGO under Jetty

Run mvn jetty:run. When you're done testing, interrupt the build with Ctrl-C to shut down Jetty.

I want to understand what I'm doing!

Maven describes projects in terms of the artifacts they produce, not the steps involved in getting there. The build behaviour is specified in an XML configuration file at the root of the project named pom.xml, which contains the human-readable and maven-readable names of the project, its version number, the type of artifact being built, any dependencies for the project, and any special plugin configurations needed for the build.

The CONGO POM specifies that the result of the build is a WAR file, with the source, resources, and web content laid out in Maven's standard build structure:

• src/main/resources is the package root for non-compiled source files, like Struts config files.
• src/main/java is the package root for Java source files.
• src/main/webapp is the root of the WAR structure and holds JSPs as well as the WEB-INF/web.xml descriptor.

Maven defines a set of standard phases (build steps), any of which will automatically trigger all the preceeding phases. Internally, phases are associated with goals provided by various plugins. There are two important lifecycles (lists of phases):

• The clean lifecycle removes all files created during the build. The standard configuration does this by deleting the target/ directory. It has one useful phase (also called clean).
• The default lifecycle builds the source tree into a single result artifact and, optionally, make that artifact available to other builds (locally or globally). It has several useful phases:
  • compile compiles code in the source tree and produces classfiles.
  • test runs unit tests (and indirectly causes them to be compiled).
  • package bundles up the compiled code and resources into the final artifact.
  • install copies the final artifact to a local repository in ~/.m2/repository/, making it available to other builds run on the same machine.
  • deploy copies the final artifact to a remote repository, making it available to builds run on other machines.

Lifecycle phases are run using the mvn phase [phase phase ...] command. You can also run specific plugin goals directly, using mvn pluginname:goalname.

TODOs for the build

• One of the stated goals for CONGO is to be able to ship WAR templates or pre-built WARs without exposing the source code. It may be worthwhile to break the build down into a JAR phase, which builds the Java pieces, and a WAR phase, which stitches the resulting JAR from the JAR phase into the WAR, rather than compiling source directly during the WAR build.
• Solve world hunger.