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
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.
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.
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:
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)
Create public/private key
And use an empty passphrase.
Ensure the ~/.ssh directory has been created with appropriate permissions, and if not then:
Copy the public key to the authorized_keys file
Assuming the authorized_keys files DOES NOT EXIST
Configure startup scripts
Create "/etc/init.d/continuum" with the following contents:
Configure Continuum for run levels
Continuum should only be running in run state 3. See init for more details.
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.
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:
If the project you are adding contains module definitions then these will also get created as separate projects in Continuum.
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.
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.
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.
Watching the logs
See the working directory
Continuum checkouts the projects into its working directly. Located at:
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.