<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>CruiseControl Getting Started with the Binary Distribution</title>
<style type="text/css" media="all">
@import "cruisecontrol.css";
</style>
<link href="print.css" type="text/css" rel="stylesheet" media="print"/>
<script type="text/javascript" src="tables.js"></script>
</head>
<body>
<div class="header">
<div class="hostedby">
Hosted By:<br/>
<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=23523&type=1" width="88" height="31" alt="SourceForge"/></a>
</div>
<div class="logo"><img alt="CruiseControl" src="banner.png"/></div>
</div>
<div class="container">
<div id="menu">
<ul id="menulist">
<li class="top"><a href="index.html">home</a></li>
<li><a href="download.html">download</a></li>
<li><a href="license.html">license</a></li>
<li><h2>documentation</h2></li>
<li><a href="overview.html">overview</a></li>
<li><a class="expandmenu" href="main/index.html">build loop</a></li>
<li><a class="expandmenu" href="reporting/jsp/index.html">results jsp</a></li>
<li><a class="expandmenu" href="dashboard.html">dashboard</a></li>
<li><a class="expandedmenu" href="gettingstarted.html">getting started</a>
<ul>
<li><p id="menuselected">binary distribution</p></li>
<li><a href="gettingstartedsourcedist.html">source distribution</a></li>
</ul>
</li>
<li><a href="main/configxml.html">config ref</a></li>
<li><a href="faq.html">faq</a></li>
<li><a class="external" href="http://confluence.public.thoughtworks.org/display/CC/Home">wiki</a></li>
<li><h2>contributing</h2></li>
<li><a class="expandmenu" href="developers.html">developers</a></li>
<li><a href="contact.html">mailing lists</a></li>
<li><a href="svn.html">source repository</a></li>
<li><p id="menubottom">Release: 2.7.3</p></li>
</ul>
</div>
<div class="content">
<h1><span class="printonly">CruiseControl</span> Getting Started with the Binary Distribution</h1>
<h2>Overview</h2>
<p>This guide covers the steps involved in getting CruiseControl up
and running using the binary distribution.</p>
<p>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".</p>
<p>The sample project models the game Connect Four. For more information
about Connect Four see
<a class="external" href="http://en.wikipedia.org/wiki/Connect_Four">http://en.wikipedia.org/wiki/Connect_Four</a></p>
<ul>
<li><a href="#Quick_Start">Quick Start</a></li>
<li>
<ul>
<li><a href="#Quick_Start.Windows">Windows</a></li>
<li><a href="#Quick_Start.Unix">Unix</a></li>
</ul>
</li>
<li><a href="#What_To_Expect">What to Expect</a></li>
<li><a href="#Command_Line_Options">Command Line Options</a></li>
<li>
<ul>
<li><a href="#Command_Line_Options.Standard">Standard Options</a></li>
<li><a href="#Command_Line_Options.JMX">JMX-related Options</a></li>
<li><a href="#Command_Line_Options.Jetty">CruiseControl with Jetty Options</a></li>
</ul>
</li>
<li><a href="#Where_to_go_Next">Where to go Next</a>
<ul>
<li><a href="#Documentation">Documentation</a></li>
<li><a href="#Mailing_Lists">Mailing Lists</a></li>
<li><a href="#Other_Tutorials">Other Tutorials</a></li>
</ul>
</li>
</ul>
<h2><a name="Quick_Start">Quick Start</a></h2>
<h3><a name="Quick_Start.Windows">Windows</a></h3>
<ol>
<li>Install CruiseControl:
<ul>
<li>If using the zip version, unzip the release to a directory. For example, <code>c:\cc-sandbox\cruisecontrol-bin-2.7.3</code></li>
<li>If using the Windows installer, run the executable. The default installation will be at <code>c:\Program Files\CruiseControl</code>.</li>
</ul>
</li>
<li>Run cruisecontrol.bat from the installation directory. For example, <code>c:\cc-sanbox\cruisecontrol-bin-2.7.3\cruisecontrol.bat</code> OR <code>c:\Program Files\CruiseControl\cruisecontrol.bat</code></li>
</ol>
<h3><a name="Quick_Start.Unix">Unix</a></h3>
<ol>
<li>Unzip the release to a directory, like
<code>~/cc-sanbox/cruisecontrol-bin-2.7.3</code></li>
<li>Check that the scripts <code>cruisecontrol-bin-2.7.3/cruisecontrol.sh</code>
and <code>cruisecontrol-bin-2.7.3/apache-ant-1.7.0/bin/ant</code> have execution permission.</li>
<li>Run <code>~/cc-sanbox/cruisecontrol-bin-2.7.3/cruisecontrol.sh</code>
from the newly unzipped directory</li>
</ol>
<h2><a name="What_To_Expect">What to Expect</a></h2>
<p>CruiseControl starts an instance of <a class="external" href="http://jetty.mortbay.org/jetty/">Jetty</a>
in a separate thread to host the reporting application. At some point in the logs you should see
a line similar to:</p>
<pre>
[cc]Aug-04 07:40:21 SocketListener- Started SocketListener on 0.0.0.0:8080
</pre>
<p>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:</p>
<pre>
[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
</pre>
<p>The daemon will execute an initial build of <code>connectfour</code> shortly after starting.
Once the initial build is complete:</p>
<pre>
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
</pre>
<p>Navigate a web browser to
<a class="external" href="http://localhost:8080">
<code>http://localhost:8080</code></a>
to view the results in the reporting application.</p>
<h2><a name="Command_Line_Options">Command Line Options</a></h2>
<h3><a name="Command_Line_Options.Standard">Standard Options</a></h3>
<table class="documentation">
<thead>
<tr>
<th>Flag</th>
<th>Required</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr>
<td>-configfile <i>filename</i></td>
<td>No</td>
<td>Relative path to CruiseControl config file. Defaults to "config.xml".</td>
</tr>
<tr>
<td>-dashboardurl <i>[dashboard url]</i></td>
<td>No</td>
<td>Home page address of your dashboard. The default value is http://localhost:8080/dashboard.</td>
</tr>
<tr>
<td>-postinterval <i>[interval number]</i></td>
<td>No</td>
<td>The interval [in seconds] that build loop post builds information to the dashboard. The default value is 5 seconds.</td>
</tr>
<tr>
<td>-postenabled <i>[true/false]</i></td>
<td>No</td>
<td>Specify whether build loop need to post builds information to the dashboard. The default value is true.</td>
</tr>
<tr>
<td>-debug</td>
<td>No</td>
<td>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.</td>
</tr>
<tr>
<td>-help or -?</td>
<td>No</td>
<td>Print the command line usage information.</td>
</tr>
</tbody>
</table>
<h3><a name="Command_Line_Options.JMX">JMX-related Options</a></h3>
<table class="documentation">
<thead><tr>
<th>Flag</th>
<th>Required</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr>
<td>-jmxport <i>[port number]</i></td>
<td>No</td>
<td>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
<a class="external" href="http://localhost:8000">http://localhost:8000</a>.
When using the Binary Distribution (or the <code>CruiseControlWithJetty</code>
start class) the Reporting for the ControlPanel JSP tab.</td>
</tr>
<tr>
<td>-rmiport <i>[port number]</i></td>
<td>No</td>
<td>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
<a class="external" href="http://mx4j.sourceforge.net/docs/ch03.html">here</a>.</td>
</tr>
<tr>
<td>-xslpath <i>directory</i></td>
<td>No</td>
<td>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.
</td>
</tr>
<tr>
<td>-user <i> user id</i></td>
<td>No</td>
<td>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.
<i>The -password flag must also be set</i>.</td>
</tr>
<tr>
<td>-password <i>password</i></td>
<td>No</td>
<td>Sets a password for the JMX HTTP Adapter. This will require users to
login to use the JMX Web interface.<i>The -user flag must also be set</i>.</td>
</tr>
<tr>
<td>-port <i>[port number]</i></td>
<td>No</td>
<td>DEPRECATED: Use -jmxport instead.</td>
</tr>
</tbody>
</table>
<h3><a name="Command_Line_Options.Jetty">CruiseControl with Jetty Options</a></h3>
<table class="documentation">
<thead><tr>
<th>Flag</th>
<th>Required</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr>
<td>-webport <i>port</i></td>
<td>No</td>
<td>Port number for Jetty. Jetty will not start unless you specify this option or -webapppath.</td>
</tr>
<tr>
<td>-webapppath <i>path</i></td>
<td>No</td>
<td>The path to the exploded cruisecontrol.war file. Defaults to ./webapps/cruisecontrol.</td>
</tr>
<tr>
<td>-ccname <i>name</i></td>
<td>No</td>
<td>A logical name to associate with this instance of CruiseControl. The name will
be displayed in the Reporting Application's status page.</td>
</tr>
</tbody>
</table>
<h2><a name="Where_to_go_Next">Where to go Next</a></h2>
<h3><a name="Documentation">Documentation</a></h3>
<p>The next step is to checkout your project code and configure CruiseControl to build it.
Read the <a href="gettingstartedsourcedist.html">Source Distribution</a> documentation,
especially the section on
<a href="gettingstartedsourcedist.html#Running_the_Build_Loop">Running the Build Loop</a>.
Note that the Binary Distribution uses a directory named <code>projects</code> in place of the
directory named <code>checkout</code>.</p>
<p>For further details about the configuration file, look at the
<a href="main/configxml.html">Configuration Reference</a>.</p>
<p>For an overview of the design of the build loop, and how to extend
the functionality of CruiseControl, look at the
<a href="main/plugins.html">Plugin</a> documentation.</p>
<h3><a name="Mailing_Lists">Mailing Lists</a></h3>
<p>To ask questions or get help with any problems you are experiencing,
send an email to the users <a href="contact.html">mailing list</a>.</p>
<h3><a name="Other_Tutorials">Other Tutorials</a></h3>
<p>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:</p>
<ul>
<li>The CruiseControl Wiki has a page <a class="external"
href="http://confluence.public.thoughtworks.org/display/CC/Getting+Started+With+CruiseControl">
Getting Started With CruiseControl</a>. This guide was originally
derived from that material.</li>
<li>The book <a class="external"
href="http://www.pragmaticprogrammer.com/sk/auto/">Pragmatic Project
Automation</a> by Mike Clark has a section "Putting A Build on
CruiseControl" that walks through getting CC up and running. This is
part of <a class="external"
href="http://www.pragmaticprogrammer.com/starter_kit/au/scheduled.pdf">
Chapter 3: Scheduled Builds</a> available online as a PDF.</li>
</ul>
</div>
</div>
</body>
</html>
