Continuous Integration with Continuum Blog


    "Integrate early, integrate often." This is the underlying principle of continuous integration, a powerful development practice recently brought into the spotlight by the Agile methodologies. Apache Continuum is a flexible, easy-to-use tool that can help you put continuous integration into action.

    In this article, we will go through the basic principals of continuous integration, and then focus on how we can use Continuum to set up a continuous integration server. We will cover installing and configuring the server and setting up a particular project, including how to check the project status and receive build failure notification in various ways.

    What is Continuous Integration?

    So what exactly is continuous integration, anyway? Continuous integration is based on the observation that the longer you wait to integrate your team's code, the harder it gets. In many projects--in fact, in more projects than many of us would like to admit--a typical development lifecycle goes something like this. Initially, coding goes along just fine; there may even be unit tests to prove it! Then, at some point in time, the team leader decides (or reminds everyone) that a delivery is due in a couple of weeks. Maybe just an alpha or a prototype, but a delivery nevertheless. So it's all hands on deck to get something working for the due deadline. The problem is, when I check out my code, it doesn't compile anymore! Or course, I know that my code is OK, so its probably some other developer's fault: maybe he forgot to commit a class, or changed one of my interfaces without asking my permission. Oh yeah, and some of the unit tests no longer work, but they belong to the DB team down the corridor, so I won't worry about them too much. And so on.

    This widely observed phenomenon is known in Agile circles, and elsewhere, as "integration hell."

    Continuous integration is the antidote to integration hell. It offers a powerful way to detect bugs and conflicts early, so that they can be fixed quickly and easily, and without too much bloodshed among team members. It basically involves automatically building and testing code at regular intervals. Team members commit their code to source configuration management very frequently (at least on a daily basis). A central server regularly checks out the latest version of the project source code, and runs a complete build, including compilation and tests. The build process automatically notifies team members of any build failures, and (hopefully) the team member responsible for committing faulty or conflicting code will immediately jump out of her chair (figuratively speaking) and rush off to fix the problem before anyone else notices!

    In practice, continuous integration can be done in one of two ways:

    1. Someone sits all day watching for code changes, and manually runs a build whenever he sees one come in. If the build fails, he gets up, walks over to the offending team member or members, and yells at them.
    2. A tool is used to automate the process.

    I would recommend the second approach.

    There are several tools, both commercial and open source, that can help to automate the continuous integration process. Among the more well-known are CruiseControl andAntHill. Even the humble make file can do the job if appropriately coached.

    More recently, members of the Maven team produced a new continuous integration tool called Continuum. As would be expected, Continuum provides very tight integration with Maven 2 projects, but also supports Ant, Maven 1, and plain old shell scripts. It boasts a very functional web dashboard, strong integration with a good many configuration management systems (including Subversion, CVS, Starteam, Clearcase, Perforce, and bazaar); mail and IM notification mechanisms (including IRC, Jabber, and MSN); and an XMP-RPC interface.

    Continuum is fast, lightweight, and undemanding. It is also self-reliant. Like Maven, it is built on the Plexus component framework, and comes bundled with its own Jetty application server. For its database needs, it uses Apache Derby, a 100-percent-Java, fully embedded database. As we will see, this makes Continuum particularly easy to install in almost any environment.

    In the rest of this article, we will take a closer look at how to install, configure, and use Continuum.

    Installing a Continuum Server

    Installing a Continuum server is easy. Make sure you have a recent JDK installed (and JAVA_HOME defined) and download the appropriate installation package from the Continuum download page. I used Java 5.0 for this article. Then just extract the downloaded file into the directory where you want to install Continuum. Extracting the installation package is pretty much all you need to do to get a basic server up and running.

    For Windows environments, Continuum comes with a handy script,bin/win32/InstallService.bat, which lets you install Continuum as a standard Windows service.

    Starting (and Stopping) the Continuum Server

    Once you have installed the files, you can start the server using one of the environment-specific start scripts. Go to the root directory of your installation and do the following:

    • For Linux boxes, use bin/linux/
    • For Macintosh OS X systems, usebin/macosx/
    • On Solaris, use bin/solaris/
    • On a Windows box, use bin\win32\run.bat.

    The basic way to start the server from the command line is as follows:

    $ bin/linux/ start Starting continuum...

    Now you can display the Continuum web administration console athttp://localhost:8080/continuum. The first time you start Continuum, you will need to provide an administrator login and password, and fill in some details about the site (see Figure 1). All subsequent connections will go directly to the Continuum administration page (see Figure 2). All users can consult the standard view, which shows the build status of the different projects on the server. To do any configuration, such as adding or configuring projects, you need to log in using the administration login you provided earlier.

    :Continuum must be configured the first time around
    Figure 1. Continuum must be configured the first time around

    The Continuum dashboard
    Figure 2. The Continuum dashboard

    Finally, if you need to stop the server, you just do the following:

    $ bin/linux/ stop Stopping continuum... Stopped continuum.

    Adding a Maven 2 Project

    Once the server is up and running, you can add a new project to the Continuous Build system. If you're not logged on, you will need to do that first.

    Let's add a Maven 2 project. Because of the particularly close integration with Maven 2, these projects are easy to add. Continuum simply reads the pom.xml file and gets all of the information it needs there (see Figure 3). However, your Maven 2 project does need to provide a minimum of useful information to make Continuum happy, so you should check that they are correctly configured.

    Adding a Maven 2 project
    Figure 3. Adding a Maven 2 project

    First of all, it will need a correctly configured Source Configuration Management (scm) section, so that it can correctly check out its own copy of the project. Here is an example using Subversion:

     <scm> <connection>scm:svn:file:///data/svn-repository/my_project</connection> <developerConnection>scm:svn:file:///data/svn-repository/my_project</developerConnection> </scm>

    Then make sure your development team is correctly documented in the developers section. You should include an entry for each developer, including (at least) their system logins, names, and email addresses. In the current version, this information is just for informative purposes. An example is shown here:

    <developers> <developer> <id>duke</id> <name>Duke Java</name> <email></email> <role>Super developer</role> </developer> ... </developers>

    Finally, you can configure the ciManagementsection, if it is not already done. This section contains the URL for the project Continuum site (so that a link can be displayed on the Maven-generated project website) and a list ofnotifiers. The notifiers tell Continuum how to inform developers in the developer list about the build results. There are many different types of notifiers available, including email and several types of instant messaging (IRC, Jabber, MSN). In the current version of Continuum, you need to provide one (or more) individual notifier for each developer in your team.

    <ciManagement> <system>continuum</system> <url>http://localhost:8080/continuum</url> <notifiers> <notifier> <type>mail</type> <configuration> <address>duke</address> </configuration> </notifier> </notifier> </notifiers> </ciManagement>

    You can also add notifiers very easily, directly from the Continuum web interface. In fact, it is probably easier to add notifiers this way. Just go to the Notifiers list in the project details page, and click on the Add button. Then choose the Notifier type (such as Mail), and provide the destination address. You can also specify when a notification message is to be sent: on build success, failures, warnings, and/or errors.

    Other Forms of Notification

    Notification by email is one thing, but notification by instant message is definitely much cooler. For one thing, you don't have to sift through your spam folder to see it, and it is pretty much, well, instant. Continuum lets you add different types of IM notifications directly from the web interface.

    Adding other Types of Projects

    Continuum supports all sorts of project types--you just have to do a bit more work configuring the non-Maven-2 ones. Maven 1 projects can be added in pretty much the same way as Maven 2 ones. For Ant and shell projects, you need to do the following:

    1. Specify the SCM details in the project creation page (see Figure 4).
    2. Go back to the home page, and display the details of the project you just created. Now you will need to manually add the project details, including the notifiers.

    Creating an Ant project
    Figure 4. Creating an Ant project

    Managing Your Project

    Once you have added your project, you can go to the Show Projects screen (see Figure 4). This is a convenient place to check out the current build status of your projects. The Build Now button lets you force an immediate build. The Build History page (see Figure 5) displays the list of all of the builds that Continuum has attempted for this project, whether they where successful or not. From here you can display detailed results for each build, including changes made to the source code repository and the build logs (see Figure 6).

    The Working Copy page lets you browse through the version of the project source code that Continuum is currently using for its builds. This is useful to check whether Continuum is using the version you think it is--don't forget, Continuum gets its source code from the configuration management repository, not from your machine, so there may be differences!

    The list of projects in the continuous integration system
    Figure 5. The list of projects in the continuous integration system

    The Build History page
    Figure 6. The Build History page

    Details of a build result
    Figure 7. Details of a build result

    Configuring the Mail Server

    The Continuum website provides a good summary of the project build status, but developers cannot be expected to stay glued to the screens watching it--they have to write a bit of code, too!

    You may need to configure the mail server for Continuum if you are not sending mail directly using a service on the server. To do this, you need to modify the application configuration file, which can be found at apps/continuum/conf/application.xml. Look for the MailSender component and modify the values to suit your environment:

     <component> <role>org.codehaus.plexus.mailsender.MailSender</role> <implementation>org.codehaus.plexus.mailsender.javamail.JavamailMailSender</implementation> <configuration> <smtp-host>localhost</smtp-host> <smtp-port>25</smtp-port> <sslProvider></sslProvider> <username>mylogin</username> <password>mypassword</password> <sslMode>true</sslMode> </configuration> </component>


    Continuum is a powerful, easy-to-use, and easy-to-configure continuous integration tool. Its excellent Maven 2 integration will make it the CI tool of choice for Maven 2 developers, but Continuum can be used with success with just about any Java project.