Hosted By:

CruiseControl Getting Started with the Binary Distribution

Quick Start

  1. Install CruiseControl: unzip the release to a directory. For example, c:\cc-sandbox\cruisecontrol-bin-2.8.4 (or ~/cc-sanbox/cruisecontrol-bin-2.8.4 on Unix).
  2. Run CruiseControl: from the installation directory run the cruisecontrol script. For example, c:\cc-sanbox\cruisecontrol-bin-2.8.4\cruisecontrol.bat (or ~/cc-sanbox/cruisecontrol-bin-2.8.4/ if on Unix; requires execute permissions for and cruisecontrol-bin-2.8.4/apache-ant-1.7.0/bin/ant).
  3. There is no step 3.

With these steps you have a running instance of CruiseControl. Browse to http://localhost:8080/dashboard to see the sample project in the dashboard, http://localhost:8080/cruisecontrol to see the jsp reporting application, http://localhost:8080/documentation for a local copy of this documentation, or to http://localhost:8000 to see the JMX interface. You can add your projects under this instance by editing cruisecontrol-bin-2.8.4/config.xml after reading about the available plugins.


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

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

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:

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
[cc]Aug-04 07:59:19 Project       - Project connectfour:  idle
[cc]Aug-04 07:59:19 Project       - Project connectfour:  next build in 5
[cc]Aug-04 07:59:19 Project       - Project connectfour:  waiting for next
time to build

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

Command Line Options

Standard Options

Flag Required Description
-configfile filename No Relative path to CruiseControl config file. Defaults to "config.xml".
-dashboardurl url No Home page address of your dashboard. The default value is http://localhost:8080/dashboard.
-postinterval [number] No The interval [in seconds] that build loop post builds information to the dashboard. The default value is 5 seconds.
-postenabled [true|false] No Specify whether build loop need to post builds information to the dashboard. The default value is true.
-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.
-log4jconfig url No URL to a log4j config (example: "file:/c:/mylog4j.xml")

Web-related Options

In addtion to these command-line options the behavior of Jetty can be customized by editing jetty.xml and the other files in the /cruisecontrol-bin-2.8.4/etc directory. Information on configuring Jetty is available on the Jetty Wiki.

Flag Required Description
-jettyxml filename No Jetty configuration xml. Defaults to "jetty.xml".
-webport port No Port number for Jetty. Jetty will not start unless you specify this option or -webapppath. The cruisecontrol start scripts have this value set as 8080 by default.
-webapppath path 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.

JMX-related Options

Flag Required Description
-agentutil [true|false] No Load JMX Build Agent utility; default is true.
-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 JMX interface at http://localhost:8000 or through the ControlPanel JSP tab or the JSP reporting application.
-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.

Getting More Information

The next step is to checkout your project code and configure CruiseControl to build it. This is covered in detail in the getting started for the Source Distribution, especially the section on Running the Build Loop.