Hosted By:
SourceForge
 

CruiseControl Getting Started with the Binary Distribution

Overview

This guide covers the steps involved in getting CruiseControl up and running using the binary distribution.

This Binary Distribution is a trimmed down version of the Source Distribution. It is fully functional and intended to work with a sample CVS project "out of the box".

The sample project models the game Connect Four. For more information about Connect Four see http://en.wikipedia.org/wiki/Connect_Four

Quick Start

Windows

  1. Install CruiseControl:
    • If using the zip version, unzip the release to a directory. For example, c:\cc-sandbox\cruisecontrol-bin-2.7
    • If using the Windows installer, run the executable. The default installation will be at c:\Program Files\CruiseControl.
  2. Run cruisecontrol.bat from the installation directory. For example, c:\cc-sanbox\cruisecontrol-bin-2.7\cruisecontrol.bat OR c:\Program Files\CruiseControl\cruisecontrol.bat

Unix

  1. Unzip the release to a directory, like ~/cc-sanbox/cruisecontrol-bin-2.7
  2. Check that the scripts cruisecontrol-bin-2.7/cruisecontrol.sh and cruisecontrol-bin-2.7/apache-ant-1.6.5/bin/ant have execution permission.
  3. Run ~/cc-sanbox/cruisecontrol-bin-2.7/cruisecontrol.sh from the newly unzipped directory

What to Expect

CruiseControl starts an instance of Jetty in a separate thread to host the reporting application. At some point in the logs you should see a line similar to:

[cc]Aug-04 07:40:21 SocketListener- Started SocketListener on 0.0.0.0:8080

Simultaneously, the main CruiseControl daemon starts. It comes pre-configured to run a continuous integration process against the sample Connect Four project. At some point in the logs you should see:

[cc]Aug-04 07:43:27 Project       - Project connectfour starting
[cc]Aug-04 07:43:27 Project       - Project connectfour:  idle
[cc]Aug-04 07:43:27 Project       - Project connectfour started
[cc]Aug-04 07:43:27 Project       - Project connectfour:  in build queue

The daemon will execute an initial build of connectfour shortly after starting. Once the initial build is complete:

BUILD SUCCESSFUL
Total time: 46 seconds
[cc]Aug-04 07:59:18 Project       - Project connectfour:  merging accumulated
log files
[cc]Aug-04 07:59:19 Project       - Project connectfour:  build successful
[cc]Aug-04 07:59:19 Project       - Project connectfour:  publishing build
results
[cc]Aug-04 07:59:19 Project       - Project connectfour:  idle
[cc]Aug-04 07:59:19 Project       - Project connectfour:  next build in 5
minutes
[cc]Aug-04 07:59:19 Project       - Project connectfour:  waiting for next
time to build

Navigate a web browser to http://localhost:8080 to view the results in the reporting application.

Command Line Options

Standard Options

Flag Required Description
-configfile filename No Relative path to CruiseControl config file. Defaults to "config.xml".
-debug No Changes the logging level of the internal log4j Logger to DEBUG. Please note that this will NOT cause your ant scripts to run as if using 'ant -debug', you need to specify that in your config.xml file.
-help or -? No Print the command line usage information.

JMX-related Options

Flag Required Description
-jmxport [port number] No Port number for the JMX HTTP adapter. This will activate the JMX admin functionality of CruiseControl. If no number is specified, this will default to 8000, which means you can access the site at http://localhost:8000. When using the Binary Distribution (or the CruiseControlWithJetty start class) the Reporting for the ControlPanel JSP tab.
-rmiport [port number] No Port number for the JMX RMI adapter and Connector Server. This will activate the JMX admin functionality of CruiseControl. If no number is specified, this will default to 1099, which is the default RMI port. If no RMI registry is running on the specified port, a registry will be started for you. You can read about the Connector Server and remoting via JSR 160 here.
-xslpath directory No The location of your custom XSLT files for use with the JMX HTTP adapter. Normally, you don't need to specify this and CruiseControl will use the style sheets that come with the distribution. This can be used to specify a directory containing your own customized versions of this stylesheets.
-user  user id No Sets a user for the JMX HTTP Adapter. This will require users to login with this user (and password see below) to use the JMX Web interface. The -password flag must also be set.
-password password No Sets a password for the JMX HTTP Adapter. This will require users to login to use the JMX Web interface.The -user flag must also be set.
-port [port number] No DEPRECATED: Use jmxHttpPort instead.

CruiseControl with Jetty Options

Flag Required Description
-webport port No Port number for Jetty. Defaults to 8080, which means that you can access the Reporting Application at http://localhost:8080.
-webapppath port No The path to the exploded cruisecontrol.war file. Defaults to ./webapps/cruisecontrol.
-ccname name No A logical name to associate with this instance of CruiseControl. The name will be displayed in the Reporting Application's status page.

Where to go Next

Documentation

The next step is to checkout your project code and configure CruiseControl to build it. Read the Source Distribution documentation, especially the section on Running the Build Loop. Note that the Binary Distribution uses a directory named projects in place of the directory named checkout.

For further details about the configuration file, look at the Configuration Reference.

For an overview of the design of the build loop, and how to extend the functionality of CruiseControl, look at the Plugin documentation.

Mailing Lists

To ask questions or get help with any problems you are experiencing, send an email to the users mailing list.

Other Tutorials

In addition to the content of this page, the following links are external resources which contain helpful information about setting up a new installation of CruiseControl from scratch: