CruiseControl Build Results Web

The CruiseControl Build Results web is a central Web portal you can navigate to and find information on any projects you have configured to be built with CruiseControl. Although you can use CruiseControl without the Build Results web, especially if you are sending formatted HTML email notifications, it is a very useful application for finding information about the status and progress of all your projects. In addition, you can configure and extend the Build Results web to display customized reports. This section describes how to install and configure the Build Results web.

Download and Install Apache Tomcat

The CruiseControl Build Results web is implemented as Java servlets and Java Server Pages (JSPs). Therefore, to install it you need a Java servlet container. I recommend that the CruiseControl Build Results web run on the same server as the one the main CruiseControl program is being executed on (such as the build server) so that it can easily access generated logs and files. In such a scenario it is best to install a lightweight container on the build server machine. Therefore, this section describes how to install Apache Tomcat for use with CruiseControl.

Apache Tomcat can be downloaded from http://jakarta.apache.org/tomcat/. There should be a link for downloading the current release. I recommend downloading the latest version of Tomcat that supports JDK 1.4.2, such as the zip file jakarta-tomcat-5.0.28.exe (or the latest version of Tomcat 5.0 that is available). After you download it, running the executable starts the Tomcat installation process. On Linux or UNIX, you need to download and extract the equivalent .zip or .tar.gz file.

In the remainder of this section, I will refer to the location in which you choose to install Tomcat as TOMCAT_HOME. On Windows this could be C:\Program Files\Apache Software Foundation\Tomcat 5.0. On Linux or UNIX it could be /usr/local/apache/Tomcat_5.0. Furthermore, I assume that you have elected to install Tomcat using the default port 8080. To check that Tomcat is installed and started, point a Web browser to http://build-server:8080/ and check that the welcome page is displayed, as shown in Figure 7.1.

Note

When you see the name build-server, replace it with the hostname of your build server machine.

Figure 7.1. Tomcat welcome screen

Configure and Install the Build Results Web

The source code for the CruiseControl Build Results web is located in the reporting/jsp directory structure of the downloaded CruiseControl distribution. Before you can install the Build Results web, you must carry out some basic configuration, specifying where the Build Results web can find the following:

• The CruiseControl logs directory, which you created in the section "Create a Workspace" in Chapter 6

• The status file, which was configured for the <currentbuildstatuslistener> entry in Chapter 6, buildstatus.txt

• The artifacts directory, which you created in the section "Create a Workspace" in Chapter 6

The best way to achieve this is to create a file called override.properties in the reporting/jsp directory, with content as follows on Windows:

# override.properties user.log.dir=C:\\Views\\javatools_int\\JavaTools\\cruisecontrol\\etc\\logs user.build.status.file=buildstatus.txt cruise.build.artifacts.dir=C:\\Views\\javatools_int\\JavaTools\\CruiseControl\\etc\\artifacts

or the following on Linux/UNIX:

# override.properties user.log.dir=/Snapshot_views/javatools_int/JavaTools/cruisecontrol/etc/logs user.build.status.file=buildstatus.txt cruise.build.artifacts.dir=/Snapshot_views/javatools_int/JavaTools/cruisecontrol/etc/artifacts

Note

On Windows, be sure to always use escaped backslashes, as in the preceding example. This is required because a backslash also marks the start of a control sequence in a string. If you do not escape the backslashes, they will not be passed correctly to the Web application.

You can then build the Build Results web. Start a command prompt and navigate to the reporting/jsp directory, and then use the following command on Windows:

>build.bat war

or the following command on Linux/UNIX:

>build.sh war

This creates a file called cruisecontrol.war in the dist directory.

To install the .war file you can use the Tomcat Web Application Manager, which is available at the Web address http://build-server:8080/manager/html, as shown in Figure 7.2. The default login for this application (if you didn't change it during installation) is the username admin with a blank password.

Figure 7.2. Tomcat Web Application Manager

If you scroll down the screen, you see a table called Deploy. It has a field called Select WAR file to upload. Click the Browse button and navigate to the directory where the cruisecontrol.war file was created. Finally, click the Deploy button. The Build Results web application should be deployed to the server, as shown in Figure 7.3.

Figure 7.3. Tomcat Web Application Manager after CruiseControl is deployed

Test the Build Results Web

To test that the Build Results web has been deployed correctly, point your browser to the address http://build-server/cruisecontrol/. You should see a screen similar to the one shown in Figure 7.4.

Figure 7.4. CruiseControl Build Results web

If you click one of the projects listed, such as RatlBankModel in this case, you can examine in more detail the results of the last and historical builds, including test results, artifacts, modifications, and some basic build metrics. This is shown in Figure 7.5.

Figure 7.5. RatlBankModel project page

Note

You can display the build results for a project only if it has been built at least once.

Of these, perhaps the list of modifications (the results of the <modificationset> element) is the most interesting, because it tells you what ClearCase elements have changed since the last build.

Using the JMX Console

Making changes via the CruiseControl config.xml is fine for persisting permanent changes, but what if you want to experiment and try new things? Similarly, what if you don't want to wait for the schedule interval to complete, and instead you want to initiate the build immediately with a different Ant target? The good news is that both of these operations can be carried out via the CruiseControl Java Management Extensions (JMX) console. JMX is an open extension of the Java language that lets you manage and monitor applications. In theory you could create your own application to interface with CruiseControl via JMX. However, in this instance, CruiseControl simply exposes its management interface as a set of Web pages. Although it isn't the friendliest of applications, the JMX console does allow you to easily navigate and set any of the attributes for a CruiseControl project, as shown in Figure 7.6.

Figure 7.6. CruiseControl JMX Console

Before you can use the JMX console, you must enable it (this is not done automatically) and specify which port it is to run on. To do this, you start CruiseControl as follows:

>cruisecontrol.bat -configfile config.xml -port 8000 -user admin-password password

This enables the JMX console on port 8000. You can change this number if it is already in use. You also can specify the -user and -password options if you want to secure access to the JMX console (if you do not want "unprivileged" users to be able to execute forced builds).

Once the JMX console has started, you can access it directly via the HTTP address http://build-server:8000/. Inside the JMX console, you should see entries for the projects you have set up. Clicking the project name takes you to a screen where you can change any of the attributes. Farther down the screen are options for pausing, resuming, or forcing a build, as shown in Figure 7.7.

Figure 7.7. CruiseControl JMX Console force build option