Kala - a PHP based GUI for CruiseControl

Latest version: 0.1.2-dev-20061004

1. Description

Kala is a PHP implementation of the CruiseControl GUI. Kala is an alternative to the existing JSP based GUI which is a fine implementation but it requires a Java web container server such as Tomcat. Most developers already have Apache HTTP server running and thus it is natural to use a PHP based GUI and avoid installing Tomcat.

Almost all Unix and Linux variants ship with Apache HTTP server and the AppServ project has created a quick installation package for running Apache HTTP server on Microsoft Windows.

2. Download

Browse releases

3. Features

Here's a quick summary of the main features of Kala.

• Easy setup and configuration: Just drop the PHP files and other included files under your Apache wwwroot, setup a couple of variables in config.properties and you are done!
• Browser based rendering: Kala generates pure XML responses and not HTML. The browser is responsible for rendering the response as HTML. This is achieved by including a special tag <?xml-stylesheet type="text/xsl" href="cruisecontrol-gui.xsl"?> in the generated XML content which causes the browser to download the specified XSL template and render the XML content as HTML.
  
  The benefit of this approach is that we don't have to generate any temporary html files on the server side and all the heavy processing is done by the client (browser). It also allows us to change the GUI logic and appearance at any time and all logs (including the old ones) will be immediately rendered according to the new look.
  
  Kala UI rendering can be also significantly faster than with the JSP frontend and you can easily view the actual XML build log with the browser by just selecting "View Page Source".
  
  The GUI rendering is based on the XSL template and CSS stylesheet. Both can be easily customized or changed entirely to create your own look and feel.
• Tightly integrated controls: the JSP version includes an embedded JMX console which is a bit ugly and often unaccessible since the firewall tends to block connections to it. Kala offers tighter integration and provides buttons for build, pause and resume directly in the summary page and project page. The calls are routed to the HTTP JMX console by the PHP script.
  
  Note! Kala also allows you to define build targets when you trigger a forced build using the GUI.
• RSS feeds: Just like the JSP version, Kala also provides an RSS feed of all projects or of any selected project. This makes it easy to monitor the build status.
• CruiseControl log viewing: You can easily view the tail of the CruiseControl log file by clicking the log link on the Kala summary page.
• Link to latest artifacts: Kala provides a static link to the generated build artifacts of the latest successful build. This helps your developers to quickly find the latest artifacts that passed the tests.

4. Screen shots

Click images to enlarge.

5. Installation

1. Unzip the distribution archive to any installation directory you like. Your Apache HTTP server must be able to read/access this directory.
   
   e.g. /opt/kala
2. Modify config.properties file and ensure that especially logs.dir and artifacts.dir point to existing directories you are using for CruiseControl. Also ensure that cruisecontrol.logfile defines an absolute path to the CruiseControl log file. Finally check that buildstatus.filename defines the filename (just the filename, not paths here) you use for publishing buildstatus.
3. Modify cruisecontrol-kala.conf configuration file and ensure that it contains paths that correctly reference the Kala installation directory and directory where build artifacts are stored.
   
   Copy (or symlink) the cruisecontrol-kala.conf in directory where Apache HTTP server can find and load it (e.g. /etc/httpd/conf.d/).
   
   You can add access restrictions to Kala GUI by using normal Apache HTTP Server instructions.
4. Restart your Apache HTTP server.
5. OK, you are done! Point your browser to the server and open projects.php. You should get a summary page of existing projects. Note! projects.php is set as the default index page in cruisecontrol-kala.conf so you can omit projects.php file in the URL if you like.

6. Troubleshooting

Problem: Build, Pause and Resume buttons don't do anything

Ensure that you have started CruiseControl with the -port or -jxmport parameter and that this port matches the port defined in config.properties

Problem: Project metrics (pie and scatter graph) do not show up

Your Apache/PHP installation does not have GD library (graphics) installed/enabled. Use phpinfo(); to ensure that GD is installed and enabled. GD setup and configuration is beyond the scope of this document. AppServ project has GD enabled by default. With WAMP5 you have to enable GD by uncommenting gd in <WAMP5-install-dir>/Apache2/bin/php.ini.

Problem: IE7 blocks JavaScript prompt which asks for build target

Select: Tools, Internet Options
Security Tab
Custom Level

Scroll down to almost the bottom of the box, and find "Allow the Pop-up Blocker to show Input Prompts"
Set to "Enable"

Alternatively you can disable forced builds with target using a setting buildwithtarget.enabled=false in config.properties. This is not recommended though since it renders an important feature useless.

Problem: Anyone can force a build in my projects!

Start CruiseControl with -user <username> and -password <password> switches. After this, Kala will require a username and password using basic authentication.

Problem: Anyone can view my projects!

Use Apache HTTP server features to restrict access to certain directories or from certain IP addresses. You can use cruisecontrol-kala.conf to define these settings. Please refer to this guide.

7. TODO

Browser based configuration

Feature which lets the user to add new projects under CruiseControl with a simple web form without manually editing config.xml. One way to do this is to require that the user first has some preconfigured project-elements in his config.xml (CruiseControl config file) and then the Kala GUI only requires a few inputs to provide the parameters for the CC "template"

Adjustable time period selection for graphs (pie/scatter)

Let user choose the time period.

Enable/disable feature for columns in summary display

Graphs for average queue/build time

8. Changelog

2006-10-04: 0.1.2-dev

- Feature "force a build with target" can be now disabled using buildwithtarget.enabled=false in config.properties
- Thanks to Alex Weinstein for improvement ideas and IE7 problem report
- Improved documentation and installation instructions
- Added cruisecontrol-kala.conf to enable easier Apache setup

2006-09-09: 0.1.1-dev

Added legends to generated graphs. Code by Cruz Pitre Jr. (cpitre). Cleanup by Jarkko.

2006-07-24: 0.1-dev - the first public release

9. Credits

Kala code was written by Jarkko Viinamäki (wyla at removethis dot iki dot fi).

Thanks to Mark Doliner for the idea to use PHP to implement the GUI.

Thanks to Cruz Pitre Jr. for providing code for implementing the graph legends.