CruiseControl Build Results JSP Installation Guide

Note that this is a brief guide to installation from the source code. For basic CruiseControl installation, go to the Getting Started page.

Getting The Source

If you have Subversion installed, you can get the entire CruiseControl source by running:

svn checkout https://cruisecontrol.svn.sourceforge.net/svnroot/cruisecontrol/trunk/cruisecontrol

Once you have obtained the source, you should have a reporting/jsp directory that contains the following:
src - The source for the JSP custom tags
test - JUnit Tests for the JSP custom tags
docs - This manual
dist - Output directory for the cruisecontrol.war distributable
images - Images used by the buildresults.jsp
lib - 3rd party libraries

Configuring

The WEB-INF/web.xml file holds the required configuration for the JSP. There are currently 2 parameters that need to be set. The first is the path to the log directory. This is required so that the JSP can read the CruiseControl log files to build the left-hand navigation. The second is the path to the current build status file. This is the file that is written by the CruiseControl build loop to let the JSP know whether it is currently building, or when the next build will occur.

You can edit them directly in the WEB-INF/web.xml file, or you can set them when you build the WAR file

Depending on the version of the JSP specification that is implemented by your app server, you may need to make one minor edit to the buildresults.jsp file. If you are using a server that is JSP 1.2 compliant, you will need to change the second line after the license text from:

<%@ taglib uri="/WEB-INF/cruisecontrol-jsp11.tld" prefix="cruisecontrol"%>

to:

<%@ taglib uri="/WEB-INF/cruisecontrol-jsp12.tld" prefix="cruisecontrol"%>

It is also possible to configure the date format used in the navigation links. To change this, we'll need to edit the navigation.jsp itself. On the <cruisecontrol:nav> tag, we can add the dateFormat attribute. Then we can set this value to be whatever we choose, as long as it's a valid date format as recognized by Java.

Building

CruiseControl uses Ant to build and package the build results web application. Everything you need to build has been included with the source that you obtained from Subversion. There is a batch file and a shell script (build.bat and build.sh respectively) provided to make building the CruiseControl web application as easy as possible. The configured cruisecontrol.war file has been created in the dist directory.

You can include options to configure the log directory, status file, and artifacts directory that you wish to use. The properties to set are user.log.dir, user.build.status.file, and cruise.build.artifacts.dir. An example (for Windows) of doing this would be:

build.bat -Duser.log.dir=C:\Cruise\logs -Duser.build.status.file=status.txt
-Dcruise.build.artifacts.dir=C:\Cruise\logs

For repeated builds a more convenient method of supplying the values you wish to use is to supply them in a file named override.properties. If a file with this name exists the properties defined within will be used when building the war file.

Deploying

Tomcat

Copy the cruisecontrol.war file from the dist directory to the %TOMCAT_HOME%/webapps directory. Then startup the server by going to the %TOMCAT_HOME%/bin directory and using the startup script. The cruisecontrol web application should deploy and you should be able to test it out by opening a web browser and going to:

http://localhost:8080/cruisecontrol/buildresults