Installation Instructions
Note that this is a brief guide to installation from the source code. For basic CruiseControl installation, go to the Getting Started page.
Installing the main build loop
1. Download Source/Build
Download the source.
If you examine the code you just downloaded, there will be a
build.bat (for Windows users) and a build.sh (for UNIX users) present
in the cruisecontrol/main directory. Execute the
appropriate script, and CruiseControl should compile. Look in the dist
directory, and you should find cruisecontrol.jar, cruisecontrol-launcher.jar,
and cruisecontrol-antprogresslogger.jar files if the build was successful.
2. Create config file / Upgrade previous version
All of the cruisecontrol configuration exists in a single config file. If you're new to cruisecontrol, you'll have to create this file; please read the explanation of the config file format
Several basic examples are provided with the distribution in the docs/helloWorld directory
3. Startup CruiseControl
CruiseControl can be started using two approaches:
-
Scripts. bin/cruisecontrol.bat or bin/cruisecontrol.sh.
This is the preferred approach, since the scripts will take care of providing you with the correct classpath and such. -
Executable jar. Type the following command:
java -jar dist/cruisecontrol-launcher.jar- If you use this, make sure CruiseControl can find the classes it needs. If you don't know which classes this are, you should just use the script. As of CruiseControl version 2.2.1, the MANIFEST.MF file is updated to contain a Class-Path entry with all the jars needed, so using java -jar should just work.
- If you're using Java 1.5/5.0, you should also provide a system property to enable CruiseControl to use its own MX4J as JMX Server instead of the JMX server that comes with the JVM: have a look at the startup scripts for more details.
- If you want CruiseControl to start up the reporting application using its
embedded Jetty server, be sure to add the flag
-webportas an argument. By default, the dashboard will be on port 8080. See the table below for more information.
In either approach, the following command line arguments can be specified:
| Flag | Required | Description |
|---|---|---|
| -jmxport [port number] | No | Port number for the JMX HTTP adaptor. 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. This is also the default that the reporting application expects for the ControlPanel JSP tab. |
| -rmiport [port number] | No | Port number for the JMX RMI adaptor 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 |
| -configfile filename | No | Relative path to CruiseControl config file. Defaults to "config.xml". |
| -xslpath directory | No | The location of your custom XSLT files for use with the JMX HTML adaptor. 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 |
| -agentutil [true/false] | No | Specify whether to load the JMX Build Agent Utility. Will only be loaded if the CCDist JMX Build Agent Utility classes are available. See: CCDist Readme for details. |
| -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 |
| -log4jconfig filename | No | URL to a log4j configuration file (for example: "file:/c:/mylog4j.xml"). Equivalent to setting the log4j.configuration system property. See Log4j Default Initialization Procedure for details. |
| -port [port number] | No | DEPRECATED: Use -jmxport instead. |
| -dashboardurl [dashboard url] | No | Home page address of your dashboard. The default value is http://localhost:8080/dashboard. |
| -postinterval [interval 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. |
| -lib [search path] | No | Specify additional directories to be included on the CruiseControl classpath.
A Launcher class is used to build the full classpath used when running CruiseControl.
If you are familiar with Ant, then this will seem very familiar. Typically, [search path] is a jar file or a directory containing jar files. Any jars or classes in the [search path] will be added to CruiseControl's classloader. The order in which jars are added to the classpath is as follows:
|
If you specify the -jmxport and/or the -rmiport parameter, a JMX Server will be started which can be used to control CruiseControl (force project builds, monitor the state of projects, change the logging level used internally, etc.).
If you specify the -webport parameter, a web server will be started with the CruiseControl reporting application.
Note that all parameters all optional; if you want to start CruiseControl using the
config.xml file in the current working directory and do not want to use JMX to
control CruiseControl, you don't need to specify any parameters.
Most users will specify (only) the -jmxport parameter, since the HTML interface to the
JMX server is very convenient.
More information on getting CruiseControl up and running can be found on the wiki.
If you need more help, subscribe to the user mailing list and ask your question there.