Install BIRT Report Viewer on Mac OSX Server

This doesn’t appear to be documented anywhere else on the web, and it’s something I’ve done a few times, so here’s how I went about it.

Thankfully, OSX Server comes with Tomcat pre-installed and ready to run.  We need to make a few minor tweaks for BIRT, but otherwise this is an easy install (much simpler than installing BIRT on a regular Mac OSX for example).

First, we enable Tomcat (which is disabled by default).  Open the Server Admin application, expand your server (add it if you need to), click on ‘Web’ in the tree, and click on ‘Settings’ in the toolbar (I’m assuming that you’ve enabled the web service here, if you haven’t you’ll need to do so).

In the ‘General’ settings tab, you’ll notice a checkbox labelled ‘Enable Tomcat’.  Check it and click save.  To verify that it’s working, visit http://localhost:8080 on the server, you should see the standard tomcat screen as in the image.

Next we need to download the latest BIRT runtime.  Visit the BIRT downloads page, and grab the latest copy of the BIRT runtime (I’m using 2.3.1 here).  Extract it somewhere, and copy the WebViewerExample folder into /Library/Tomcat/webapps, renaming the folder to something more meaningful, like birt-viewer.

Now, as per the deployment instructions for Tomcat 6, we need to grab a copy of the commons logging library.  Download it from here (I’m using the 1.1.1 binary release), extract it, and copy the jars (I’m not sure which ones it needs, so just copy them all) into /Library/Tomcat/lib/.

Next, we have some minor tweaks to make.  Because java on *nix generally needs an X-server running to generate images (and OSX won’t normally be running one), we need to instruct java to run headless.  To do this (this is how I do it, there may be a better way) add the following line to somewhere near the top of the /Library/Tomcat/bin/ (just after the licensing jargon is a good place)

export CATALINA_OPTS=-Djava.awt.headless=true

Also, since a server probably won’t have any printers set up, we need to tell BIRT not to try to use any.  We do this by editing the file /Library/Tomcat/webapps/birt-viewer/WEB-INF/web.xml and changing BIRT_VIEWER_PRINT_SERVERSIDE to OFF as follows:


That’s it then, save your changes and restart Tomcat (by restarting the Web service in Server Admin).  Test that it’s all working correctly by viewing the test report.

  1. #1 by Bricky on February 13, 2009 - 3:37 pm

    Quick note which may save someone some headaches:

    OSX updates are likely to overwrite /Library/Tomcat/bin/ at some stage, including your modifications. So be warned.

(will not be published)