I was entasked recently with getting a continuous integration environment set up. phpUnderControl seems to be the tool of choice for this these days, so I started off in that direction. According to its web site, "phpUnderControl is an addon application for the continuous integration tool CruiseControl, which integrates some of the best PHP development tools."

Obviously I needed to install PHP itself. CruiseControl is a daemon written in Java, so that needed to be installed as well. Our Linux distro of choice is Debian. With these requirements, I set out.

First I downloaded a minimal Debian ISO and installed it to a VirtualBox VM, mostly selecting the default configuration settings. (I made a few changes for my available screen resolutions for X.)

While Linux distributions generally include packages for various JVM implementations, it's often recommended to run the canon implementation from Sun. Debian doesn't come with a package for this, but I was able to find a brief article on how to install one:

echo 'deb http://www.backports.org/debian etch-backports main contrib non-free' >> /etc/apt/sources.list
aptitude update
aptitude -t etch-backports install sun-java6-jdk
update-alternatives --config java

I ran into a small issue later when actually trying to run CruiseControl that this forum thread helped me solve. Apparently CruiseControl expects Java to be in /bin/java rather than /usr/bin/java where the Sun package installs it. The easiest way to get around this is simply to create a symbolic link:

ln -s /usr/bin/java /bin/java

Moving onto CruiseControl itself, the first hit on Google seemed to be a good (if somewhat dated) reference. Setting the JAVA_HOME environmental variable is accurate and straightforward:

echo 'JAVA_HOME="/usr/lib/jvm/java-6-sun"' >> /etc/environment
source /etc/environment

The commands for downloading and extracting CruiseControl need to be updated to the latest stable release, which is 2.8.1:

cd /opt/
wget http://switch.dl.sourceforge.net/sourceforge/cruisecontrol/cruisecontrol...
unzip cruisecontrol-bin-2.8.1.zip -d /opt
ln -s /opt/cruisecontrol-bin-2.8.1 /opt/cruisecontrol

Next, in order to follow the PEAR route as this guide does, we need to install PHP and PEAR. At this time, you also need to install the PHP headers (php5-dev) package if you want to be able to install packages via the pecl installer, like Xdebug for generating code coverage reports.

sudo apt-get install php5 php5-dev php-pear
pecl install xdebug

Debian uses a non-standard naming scheme for its PHP package, which throws off the pear installer when it checks for minimum PHP version requirements. As such, you have to modify the commands slightly to have them work.

pear channel-discover components.ez.no
pear install -o -f ezc/Graph-beta
pear channel-discover pear.phpunit.de
pear install -a phpunit/phpUnderControl-beta

Now patch the CruiseControl installation for phpUnderControl.

phpuc install /opt/cruisecontrol
phpuc example /opt/cruisecontrol

The patched configuration file won't point to the correct filesystem location for housing generated graph images. This is addressed (albeit rather tersely) in the phpUnderControl FAQ. To fix this, open up /opt/cruisecontrol/config.xml in your preferred text editor. Find this area of the file:

<?xml version="1.0"?>
<cruisecontrol>
<project name="php-under-control" ... >
...
<publishers>
...
<artifactspublisher dir="projects/${project.name}/build/api" dest="logs/${project.name}" subdirectory="api"/>
<artifactspublisher dir="projects/${project.name}/build/coverage" dest="logs/${project.name}" subdirectory="coverage"/>

In particular, you're looking for the two artifactspublisher tags. In their dest attributes, change "logs" to read "artifacts" instead.

Finally, start CruiseControl.

cd /opt/cruisecontrol
./cruisecontrol.sh

Then open up a browser and access phpUnderControl by going to http://localhost:8080/cruisecontrol. From there, you can click on the linked name of a project to get information specific to that project. You can also browse to http://localhost:8080, which will present you with links to other areas that CruiseControl provides.

At this point, you may want to make some customizations to the configuration. Note that CruiseControl will run builds every five minutes default and will reload the configuration file each time before building. The Getting Started section of the phpUnderControl documentation is especially good for guiding you through commonly desired customizations. The Continuous Integration section of the phpUnit documentation is also a good reference.

Projects live under /opt/cruisecontrol/projects and are added to CruiseControl via the config.xml file referenced earlier. The php-under-control example project added when CruiseControl was patched for phpUnderControl should provide a good starting point and the two references cited above should help to flesh it out to your liking.

One last thing: to terminate the CruiseControl process, you can kill the process by running the command below or use a utility script like this one to allow for easily starting, stopping, or restarting the daemon. Either way, the daemon will gracefully shut down.

kill `cat /opt/cruisecontrol/cc.pid`

And that's a wrap. Hope it's been informative.