<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>CruiseControl Dashboard</title>
<style type="text/css" media="all">
@import "cruisecontrol.css";
@import "dashboard.css";
</style>
<link href="print.css" type="text/css" rel="stylesheet" media="print" />
</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" alt="SourceForge" height="31" width="88" /></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><p id="menuselected" class="expandedmenu">dashboard</p>
<ul>
<!--<li><a href="widgets.html">widgets</a></li>-->
<li><a href="buildgrid.html">build grid</a></li>
</ul>
</li>
<li><a class="expandmenu" href="gettingstarted.html">getting started</a></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>Dashboard</h1>
<h2>What is the CruiseControl Dashboard?</h2>
<p>The CruiseControl Dashboard is a powerful tool to help you visualise your project statuses. Previous project build result is colour-coded so that you can get an instant snapshot of how your projects are doing instantly. The build results are overlayed with icons showing the current status of the project (for example paused, queued or building).</p>
<p><img src="dashboard/dashboard.jpg" alt="dashboard" /></p>
<p>When you place your mouse over the project builds, represented by the colored squares, you can see more information on that project, such as the project name, the server the project is running on, and when the last build occurred.</p>
<h3>What do the squares mean?</h3>
<p>In general, the squares will either have green or red as the background color. A red background indicates that the last build failed, while a green background indicates that it passed. The longer the build has been in its current state, the darker the colour will be. The exception is projects that are building - these will be green if the project passed last time it built, and orange if the project failed last time.</p>
<p>Here are some examples of the kinds of status you are likely to see. Many more combinations are possible, but you should have no problem deducing them from the examples below</p>
<ul style="list-style-type: none; list-style-image: none; list-style-position: outside;">
<li class="success-long">This indicates a project build has been successful for more than 24 hours, and is currently in the queue waiting to build.</li>
<li class="success">This indicates a project build has been successful for less than 24 hours.</li>
<li class="failed-long">This indicates a project build that has failed for more than 24 hours.</li>
<li class="failed">This indicates a project build that has failed for less than 24 hours and is currently paused.</li>
<li class="building">This indicates a project that passed last time it ran and is currently building.</li>
<li class="inactive">This indicates an inactive or discontinued project*.</li>
</ul>
<p style="font-size: smaller">* Inactive projects are ones that are defined in CruiseControl's configuration file but have never been built (in other words, CruiseControl can't find any logs corresponding to this project). A discontinued build is one that has log files from previous builds, but is not defined in CruiseControl's configuration file.</p>
<p>Here is a list of actions you can perform: access the RSS feed to the project build, the XML feed for CCTray, and the CruiseControl JMX console.</p>
<p><img src="dashboard/actions.jpg" alt="actions" /></p>
<h2>Builds page</h2>
<p><img src="dashboard/buildpage.jpg" alt="buildpage" /></p>
<p>This is the build page. It enables you to look at each project build and its status. You can perform the following actions on each project build:</p>
<ul style="list-style-type: none; list-style-image: none; list-style-position: outside;">
<li class="view-all-successful">View all successful builds</li>
<li class="view-all-builds">View all builds</li>
<li class="force-build">Force build</li>
<li class="control-panel">Access each individual project build's RSS feed and the CruiseControl JMX console</li>
</ul>
<h2>Build Detail Page</h2>
<p><img src="dashboard/builddetail.jpg" alt="builddetail" /></p>
<p>The build detail page contains project build information such as the last successful build, build number, duration of the build and the last 25 builds.</p>
<h2>Build Detail Page For Building Project</h2>
<p><img src="dashboard/building.jpg" alt="building" /></p>
<p>This is the build detail page for a project that is currently building. Whilst the project is building, the build output is displayed on-screen.</p>
<h2>Administration Page</h2>
<p><img src="dashboard/admin.jpg" alt="admin" /></p>
<p>On this page you can see details about the configuration of the dashboard, such as which build it is, the type of OS and version of the JVM it is running on. By clicking in the "configuration" sub-tab, you can see where the dashboard is reading its configuration from, and the contents of its configuration file.</p>
<h2>Limitations of the dashboard</h2>
<p>There are known limitations of the dashboard. They are:</p>
<ul>
<li>If you remove a project's log files, the dashboard won't automatically discover this and mark the project inactive. You need to refresh the page in the browser first. Note also that if you delete a project's log folder, CruiseControl won't re-create it unless you restart CruiseControl.</li>
<li>If you remove a project from CruiseControl's config.xml file, the dashboard won't automatically discover this and mark the project discontinued. You need to refresh the page in the browser first.</li>
<li>Although the build loop will automatically pick up changes made to config.xml, the dashboard won't pick up changes when you change dashboard-config.xml. You'll need to restart the dashboard for these changes to take effect.</li>
</ul>
<h2>Installation guide</h2>
<p>There are three ways you can configure the dashboard. In order of precedence (highest first), they are:</p>
<ul><li><strong>web.xml of your J2EE server</strong>. This is deprecated, since you will have to unpack the distribution in order to edit this file.</li>
<li><strong>dashboard-config.xml</strong>. This is the preferred way to configure the dashboard. A default dashboard-config.xml file is distributed with CruiseControl, and lives in the same place as the config.xml file used to configure the build loop.</li>
<li><strong>system properties</strong>. You can use system properties to override the settings in the configuration files -- see below.</li>
</ul>
<h3>System property</h3>
<p>Administrators can pass system properties through cruisecontrol.sh/cruisecontrol.bat or the startup script of the web
container.</p>
<table class="documentation">
<thead> <tr>
<th>Property</th>
<th>Value</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>cc.config.forcebuild</td>
<td>enabled/disabled</td>
<td>enabled</td>
<td>whether users can force a build from gui</td>
</tr>
<tr>
<td>cc.logdir</td>
<td>String</td>
<td>logs</td>
<td>Used to specify the full path to your CruiseControl logs directory.</td>
</tr>
<tr>
<td>cc.artifacts</td>
<td>String</td>
<td>artifacts</td>
<td>Used to specify the full path to your CruiseControl artifacts directory.</td>
</tr>
<tr>
<td>dashboard.config</td>
<td>String</td>
<td>dashboard-config.xml</td>
<td>Used to specify the full path to the dashboard configuration file.</td>
</tr>
</tbody>
</table>
<h3>Dashboard Configuration File</h3>
<p>By default Dashboard uses <em>dashboard-config.xml</em>, which is found in the CruiseControl installation
directory. The administrator can specify the location of the dashboard configuration file in <em>cruisecontronl.sh/cruisecontrol.bat</em> by setting the value of the
<em>dashboard.config</em> system property.</p>
<h2><a name="buildloop"><buildloop></a></h2>
<div class="hierarchy">
<pre><dashboard><br /> <buildloop></pre>
</div>
<p>The <buildloop> tag is used to specify properties related to cruisecontrol build loop. </p>
<h3>Attributes</h3>
<table class="documentation">
<thead> <tr>
<th>Attribute</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="eggrow">
<td>logsdir</td>
<td>This should be the full path to your CruiseControl logs directory.</td>
</tr>
<tr class="oddrow">
<td>artifactsdir</td>
<td>This should be the full path to your CruiseControl artifacts directory.</td>
</tr>
</tbody>
</table>
<h2><a name="features"><features></a></h2>
<div class="hierarchy">
<pre><dashboard><br /> <features></pre>
</div>
<p>The <features> tag is used to specify properties which customize the behaviour of the dashboard. </p>
<h3>Attributes</h3>
<table class="documentation">
<thead> <tr>
<th>Attribute</th>
<th>Description</th>
</tr>
</thead> <tbody>
<tr class="oddrow">
<td>allowforcebuild</td>
<td>whether users can force a build from the GUI. true or false.</td>
</tr>
</tbody>
</table>
<h2><a name="trackingtool"><trackingtool></a></h2>
<div class="hierarchy">
<pre><dashboard><br /> <trackingtool></pre>
</div>
<p>The <trackingtool> tag is used to specify properties which can be used to create hyperlinks from commit comments to project management tools. Each of your projects can have zero or one <trackingtool>s </p>
<p>The dashboard will parse your commit message to find the story number which follows the keywords specified, and will generate a hyperlink using the baseurl you define and the story number.</p>
<p>For example: If you check in source code with message "I fixed bug #425" and define your <trackingtool> as below:</p>
<p> <trackingtool projectname="cc" baseurl="http://mingle05/projects/ccee/cards/" keywords="#,build"/></p>
Then the dashboard will create the hyperlink "<a
href=http://mingle05/projects/ccee/cards/425>I fixed bug #425</a>" for the commit message.
<h3>Attributes</h3>
<table class="documentation">
<thead> <tr>
<th>Attribute</th>
<th>Description</th>
</tr>
</thead> <tbody>
<tr class="oddrow">
<td>projectname</td>
<td>Your project name in cruisecontrol.</td>
</tr>
<tr class="eggrow">
<td>baseurl</td>
<td>The base url of your project in project management tool</td>
</tr>
<tr class="oddrow">
<td>keywords</td>
<td>The keywords to look for in your commit message, comma separated.</td>
</tr>
</tbody>
</table>
<h2><a name="subtabs"><subtabs></a> (deprecated)</h2>
<div class="hierarchy">
<pre><dashboard><br /> <subtabs></pre>
</div>
<p>The <subtabs> tag is used to specify widget plug-ins for the build detail page. You can have zero or one subtabs tags, which can contain any number of <subtab> tags.</p>
<p><strong>Note that the dashboard widget API is deprecated and will be replaced in a future version of CruiseControl. We strongly recommend developers do not create widgets using this API, as it will not be supported in the future.</strong></p>
<p>Example:</p>
<pre><subtabs>
<subtab class="net.sourceforge.cruisecontrol.dashboard.widgets.ErrorsAndWarningsMessagesWidget" />
</subtabs></pre>
<h2>Context parameter (Deprecated. Use System Property or Dashboard configuration file instead.)</h2>
<p>Administrators can manually edit the web.xml to configure the
dashboard application.</p>
<table class="documentation">
<thead> <tr>
<th>Property</th>
<th>Value</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead> <tbody>
<tr>
<td>cruisecontrol.config.forcebuild</td>
<td>enabled/disabled</td>
<td>enabled</td>
<td>whether users can force a build from gui</td>
</tr>
<tr>
<td>cruisecontrol.logdir</td>
<td>String</td>
<td>logs</td>
<td>This should be the full path to your CruiseControl logs
directory.</td>
</tr>
<tr>
<td>cruisecontrol.artifacts</td>
<td>String</td>
<td>artifacts</td>
<td>This should be the full path to your CruiseControl
artifacts directory.</td>
</tr>
</tbody>
</table>
</div>
</div>
</body>
</html>
