How to Install CruiseControl

Setting Up and Configuring CruiseControl - learn how to install cruisecontrol.

This page is primarily focused on installing and configuring CruiseControl on Linux which includes

- Procedures on Running Your Very First CruiseControl Server

- Implementation of phpUnderControl

- Adding New Projects on CruiseControl

- Integration of Some of the Best PHP Development Tools.

Requirements

Some pre-requisites depends upon the components that you are going to integrate with CruiseControl. But for the default setup of CruiseControl, which are listed below, we need to have the latest '''Java''' installed.

- CruiseControl Server

- CruiseControl Web Application / Dashboard

- Developer desktop running CCTray

On this tutorial, we'll be integrating different components that in general requires '''Java''' and '''PHP'''. For each components' pre-requisites, see our listing as follows.

Code Repository

- SVN

Build Tool

- Ant

Unit Testing

- PHPUnit

Graphical Metrics

- phpUnderControl

API Documentation

- PhpDocumentor

Code Analysis

- PHP Depend
- PHP Mess Detector
- PHP_CodeSniffer

Site Performance and Load Testing

- YSlow
- Siege

Profiling and Debugging

- Xdebug
- xdebugtoolkit
- Graphviz
----
Installation Procedures

Here are some easy steps to have your very first CruiseControl running. For consistency, all through out the tutorial, we'll work under '''/opt''' directory or unless indicated.

JDK

Download

Get the latest '''[http://java.sun.com/javase/downloads/index.jsp JDK]''' which includes JRE. As of to this writing JDK version is '''JDK 6 Update 20'''

Install

For detailed installation instructions visit http://java.sun.com/javase/6/webnotes/install/index.html.

CruiseControl

Download

As of to this writing CruiseControl version is '''2.8.3'''

wget http://nchc.dl.sourceforge.net/project/cruisecontrol/CruiseControl/x.x.x/cruisecontrol-bin-x.x.x.zip

Unpack

unpack cruisecontrol-bin-x.x.x.zip.

unzip cruisecontrol-bin-x.x.x.zip

Symbolic link

ln -s cruisecontrol-bin-x.x.x cruisecontrol

Start CruiseControl

Change directory to /opt/cruisecontrol and execute cruisecontrol script.

./cruisecontrol.sh

'''Note''': JAVA_HOME must be properly configured.

Check CruiseControl

If everything goes well, you should be able to access the main page showing '''connectfour''' project.

Visit http://127.0.0.1:8080/cruisecontrol/

Manage CruiseControl

With this script, you'll be able to control CruiseControl Server.

Copy paste this code and save as an executable file (cruisecontrol) in /etc/init.d

Usage: /etc/init.d/cruisecontrol {start|stop|restart}

#!/bin/sh
### BEGIN INIT INFO
# Provides: cruisecontrol
# Required-Start: $local_fs $remote_fs $network $syslog
# Required-Stop: $local_fs $remote_fs $network $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Start/stop cruisecontrol CI server
### END INIT INFO
#
# cruisecontrol This init.d script is used to start cruisecontrol.
# It basically just calls cruisecontrol.sh.

# ENV="env -i LANG=C PATH=/usr/local/bin:/usr/bin:/bin"

CCON_PATH=/opt/cruisecontrol
CCON_USER=root
PIDFILE=$CCON_PATH/cc.pid
LOGFILE=/var/log/cruisecontrol.log

. /lib/lsb/init-functions

log_daemon_msg() {
logger "$@";
}

log_end_msg() {
[ $1 -eq 0 ] && RES=OK; logger ${RES:=FAIL};
}

ccon_is_running() {
if [ -f $PIDFILE ]; then
PID=`cat $PIDFILE`
PID_COUNT=`ps aux | grep -E $PID | grep -v grep | wc -l`
if [ $PID_COUNT = 1 ]; then
return 1
fi
fi

return 0
}

ccon_start() {
ccon_is_running
rc=$?
if [ $rc -eq 1 ]; then
log_failure_msg "CruiseControl is already running"
exit
else
log_daemon_msg "Starting CI server" "CruiseControl"
cd $CCON_PATH
sudo -H -u $CCON_USER ./cruisecontrol.sh >> $LOGFILE 2>&1
log_end_msg $?
fi
ccon_is_running
rc=$?
if [ $rc -eq 1 ]; then
log_success_msg "Starting CI server" "CruiseControl"
fi
}

ccon_stop() {
ccon_is_running
rc=$?
if [ $rc -eq 1 ]; then
log_daemon_msg "Stopping CI server" "CruiseControl"
PID=`cat $PIDFILE`

retval=0
i=0
while $(kill "$PID" 2> /dev/null); do
if [ $i = '60' ]; then
echo ""
log_failure_msg "CruiseControl is taking too long to shutdown"
retval=1
break
else
if [ $i = '0' ]; then
echo -n " ... waiting "
else
echo -n "."
fi
i=$(($i+1))
sleep 1
fi
done

log_end_msg $retval
else
log_failure_msg "CruiseControl is not running"
exit
fi
ccon_is_running
rc=$?
if [ $rc -eq 0 ]; then
log_success_msg "Shutting down CI server" "CruiseControl"
fi
}

ccon_status() {
ccon_is_running
rc=$?
if [ $rc -eq 1 ]; then
PID=`cat $PIDFILE`
log_success_msg "CruiseControl is running (pid $PID)."
else
log_failure_msg "CruiseControl is not running."
fi

}

case $1 in
start)
ccon_start
;;
stop)
ccon_stop
;;
restart)
ccon_stop
ccon_start
;;
status)
ccon_status
;;
*)
log_success_msg "Usage: /etc/init.d/cruisecontrol {start|stop|restart|status}"
exit 1
;;
esac

FAQ and Troubleshooting

Q: 404 error when accessing cruisecontrol on 8080 web interface.
A: Check if you have the latest JDK installed.

Q: Encountered error: "/usr/bin/build-classpath: error: Could not find xml-commons-apis Java extension for this JVM".
A: Install xml-commons-apis

Q: Encountered error: "Unable to instantiate specified logger `class net.sourceforge.cruisecontrol.builders.AntProgressLogger` : `java.lang.ClassNotFoundException`".
A: On config.xml, under schedule > ant tag, indicate `loggerclassname="org.apache.tools.ant.XmlLogger"` with showProgress="true"

Q: PHPUnit can't create coverage report.
A: Xdebug needs to be installed and properly configured.

Q: Missing test results on phpUnderControl Tests tab.
A: On config.xml, under log > merge tag, dir attribute should be pointing to PHPUnit's log output directory.

Q: Missing graphs on phpUnderControl Metrics tab.
A: On config.xml, under publishers tag, add this line:

Q: PHP Mess Detector doesn't generate report.
A: Set included paths using bootstrap file then PHPUnit will create PMD report for every instantiated class w/in the test units.

Q: Can't create log metrics using PHPUnit.
A: PHPUnit’s -log-metrics is depreciated. Use PHP_Depend instead.

Q: Can't create PMD reports using PHPUnit.
A: PHPUnit’s -log-pmd is depreciated. Use PHP Mess Detector instead.

Q: How to share project logs, coverage, and docs on Dashboard Artifacts.
A: Make use of symbolic links. Create artifacts.php script that will create symlinks, edit config.xml then add this line right after

Q: Encountered error "Unable to connect to build loop".
A: This happens when project's dashboard is currently in building process. Try to resolve machine hostname to its correct IP Address.

Q: Encountered error "ant logfile /opt/cruisecontrol-bin-2.8.3/log.xml does not exist".
A: On config.xml, under schedule > ant tag, indicate `loggerclassname="org.apache.tools.ant.XmlLogger"` with showProgress="true"

Q: CruiseControl Mbean (http://127.0.0.1:8000/mbean?objectname=CruiseControl%20Project:name=apw) doesn't show as iframe on dashboard.
A: Try to resolve machine hostaname to its correct IP Address.

Q: Encountered error when forcing build: "Error communicating with build loop on: `rmi://127.0.0.1:1099`".
Could not force build on java.io.IOException: `javax.naming.CommunicationException`.
[Root exception is java.rmi.ConnectIOException: Exception creating connection to: 172.27.23.214; nested exception is: `java.net.NoRouteToHostException`: No route to host.
A: Try to resolve machine hostaname to its correct IP Address.

Q: SVN was not able to see the log changes on my repository, thus build process is not triggered.
A: When using SVN for , be sure to use the same username and password you used to check out repository.