CruiseControl Getting Started with the Binary Distribution
Quick Start
- 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.4on Unix). - 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/cruisecontrol.shif on Unix; requires execute permissions forcruisecontrol.shandcruisecontrol-bin-2.8.4/apache-ant-1.7.0/bin/ant). - 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.
Overview
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 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/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.