Overview

Continuous Integration is what gives you confidence that your project is healthy. By continuously compiling, unit testing and running reports against your project you can gain confidence that there are few "gotchas" when it comes time to release.

This guide will recommend installing continuous integration on a single machine and to make this guide a bit more readable this machine will be called NUCLEUS.

There are quite a few continuous integration solutions available.

• http://maven.apache.org/continuum/ Continuum
• http://cruisecontrol.sourceforge.net/index.html CruiseControl
• http://luntbuild.javaforge.com/ LuntBuild

This guide will walk through Continuum

Prerequisites

Shell access to NUCLEUS

Shell access is needed to exectute commands and to configure Continuum. This may be done in conjunction with a sysadmin if you do not have the required privileges. Recommend a "continuum" user with group "maven" with home directory "/usr/local/continuum".

The continuum account should be given a password as the deploy commands which use ssh will fail if the account does not have a password (see http://www.openssh.com/faq.html#3.0 Portable OpenSSH Questions). I use a random password generator to create the password as no human will ever need to use it, they should be using sudo (or equivalent) to change accounts.

ssh access to NUCLEUS

You need ssh access to the NUCLEUS server to deploy both the maven artifacts and the web site.

Continuum 1.0.3

See http://maven.apache.org/continuum/download.html for access to http://www.apache.org/dyn/closer.cgi/maven/binaries/continuum-1.0.3-bin.tar.gz

Install and Configuring Continuum

As the continuum user follow the instructions at http://maven.apache.org/continuum/guides/getting-started/index.html and in Better Builds with Maven

Allow local files for POM

If you don't have web browsable CVS for accessing your POMs then you will need to allow Continuum to load a POM from file. Remove the comments around the allowedScheme for file.

<implementation>org.codehaus.plexus.formica.validation.UrlValidator</implementation>
<configuration>
  <allowedSchemes>
    ...
    <allowedScheme>file</allowedScheme>
  </allowedSchemes>
</configuration>

Then manually checkout your project and reference the file's location on disk when adding the project to Continuum

.cvspass file creation

If you are using CVS then Continuum will need to be able to execute CVS commands in batch mode, without human intervention. This will mean that any passwords needed by the CVS server are stored in the .cvspass file. As the continuum account user execute the cvs login command which will create the .cvspass file. Continuum will use the anonymous user to checkout the project, so run the following command as the continuum user and use an empty password:

cvs -d:pserver:anonymous@HOST:CVSROOT login

Configure settings.xml file

Run mvn for the first time, it will create the ~/.m2 directory structure for you.

You will then need to create a ~/.m2/settings.xml file and customize it to suit the environment. It should be very similar to the settings.xml file needed for a developer. You will need to add the inhouse servers to the list (as the settings file assumes developers do not deploy to the inhouse repositories directly)

        <server>
            <id>inhouse</id>
            <username>continuum</username>
            <privateKey>/usr/local/continuum/.ssh/id_rsa</privateKey>
            <filePermissions>664</filePermissions>
            <directoryPermissions>775</directoryPermissions>
        </server>

        <server>
            <id>inhouse_snapshot</id>
            <username>continuum</username>
            <privateKey>/usr/local/continuum/.ssh/id_rsa</privateKey>
            <filePermissions>664</filePermissions>
            <directoryPermissions>775</directoryPermissions>
        </server>

Create public/private key

Run

ssh-keygen -t rsa -C "Continuum Key for NUCLEUS"

And use an empty passphrase.

Ensure the ~/.ssh directory has been created with appropriate permissions, and if not then:

chmod -R go-rwx ~/.ssh/

Copy the public key to the authorized_keys file

Assuming the authorized_keys files DOES NOT EXIST

cd ~/.ssh
cp id_rsa.pub authorized_keys

Configure startup scripts

Create /etc/init.d/continuum

Create "/etc/init.d/continuum" with the following contents:

#!/sbin/sh
#

CONTINUUM_HOME=/usr/local/continuum
USER=continuum

if [ ! -d ${CONTINUUM_HOME} ]; then
        echo "Error: CONTINUUM_HOME does not exist: ${CONTINUUM_HOME}"
        exit 1
fi

case "$1" in
start)
        su ${USER} -c "${CONTINUUM_HOME}/bin/continuum start"
        ;;
restart)
        su ${USER} -c "${CONTINUUM_HOME}/bin/continuum restart"
        ;;
stop)
        su ${USER} -c "${CONTINUUM_HOME}/bin/continuum stop"
        ;;
*)
        echo "Usage: $0 {start|stop|restart}"
        exit 1
        ;;
esac

Configure Continuum for run levels

Continuum should only be running in run state 3. See init for more details.

ln -s /etc/init.d/continuum /etc/rc3.d/S99continuum

Adding Projects

If you don't have a web browsable CVS then the workaround is to manually checkout the module on the host and then use a file reference to the pom.

mkdir ~/tmp-cvs
cd ~/tmp-cvs
cvs -d:pserver:anonymous@HOST:CVSROOT co MODULE

If prompted for a password enter it as it will get stored into ~/.cvspass as continuum will need to use this file at run time for the password

Once checked out you can then provide an absolute reference via file url, for example:

file://localhost/usr/local/continuum/tmp-cvs/MODULE/pom.xml

If the project you are adding contains module definitions then these will also get created as separate projects in Continuum.

Multi-module builds

Often as you are developing you might not have all the modules defined before the project has been added to Continuum. Currently once a project has been added to Continuum it does not check if the module definitions have changed and automatically add the module as a project.

If you want to add a new module to a multi-module build then specify the module in the project's pom.xml file. Then either checkout the module, or update the checkout of the parent project (which would include the module) and then reference the module pom file in the add project screens.

Build Definitions

The default goals for Maven are "clean, install". However since Continuum is continuously integrating the projects it makes sense for Continuum to also deploy the snapshot versions when the build is successful. This means the goals should be "clean, deploy". Unfortunately there is no way to mass edit these entries and no way to specify that this should be the default, so you must manually modify all your projects as they get added.

Nightly Builds

The nightly build should create and deploy the site as well so that the project documentation is kept up to date.

Unfortunately there appears to be no way to tell Continuum that a second build definition should be forced to run and because the primary build definitions have completed successfully the secondary build definition fails to fire. The work around for this appears to be to add a second copy of the project to Continuum and to make it's primary build definition equal to the nightly build definition. Since the project contains module definitions it means deleting these additional projects that are automatically added to Continuum.

Goals = site site:deploy
Arguments = --batch-mode
POM File =pom.xml
Profile = DEFAULT
Schedule = NIGHTLY_SITE_BUILD
From = Project

Where NIGHTLY_SITE_BUILD is (runs at 7:15 pm mon-fri)
Name = NIGHTLY_SITE_BUILD
Description = Build and deploy the site nightly
Cron = 0 15 19 ? * MON-FRI
Quiet Period (seconds) = 0

Watching the logs

tail -f ~/continuum-1.0.3/logs/wrapper.log

See the working directory

Continuum checkouts the projects into its working directly. Located at:

~/continuum-1.0.3/apps/continuum/working-directory. 

Problem Solving

Continuum fails with errors

If there are any failures with Continuum you should see useful information as to the reason in the wrapper.log file. Often the failure is because the maven commands Continuum is attempting to run are requiring human intervention and hence are failing when run in batch mode.

Manually run the same command that Continuum is trying to run in the working directory of the failing project and ensure that it runs correctly. Once you have fixed any errors that cause the build to run incorrectly then Contiuum should also be able to build your project.