CiviCRM Community Forums (archive)

This is a quick guide based on my experience of installing BIRT to view reports (keyword: CiviReport) on our CiviCRM server.

The environment is Debian Etch. Please contribute to this documentation by adding your own experiences and comments! I was completely unfamiliar with Tomcat when I started this, so I'm sure it can be improved.

I'm posting it both to the wiki (Installing Birt Viewer on Debian) and the forum in the hope that it will get more feedback.

Install JDK and Tomcat

I did this on Debian by enabling the non-free repositories in /etc/apt/sources.list, and then running

sudo apt-get update
sudo apt-get install sun-java5-jdk
sudo apt-get install tomcat5.5 tomcat5.5-admin tomcat5.5-webapps

The webapps package is probably superfluous, but I wanted to have something to check if my Tomcat was working first!

Once Tomcat is started, check that you can access it - my Tomcat came up at http://MYHOSTNAME:8180/

NB: On Debian, I found that BIRT wouldn't run unless I changed the TOMCAT_SECURITY entry in /etc/default/tomcat5.5 from "YES" to "NO". Another reported approach on the internet, but which I didn't succeed with, is to add an entry in your /var/lib/tomcat5.5/conf/catalina.policy similar to
grant codeBase "file:${catalina.base}/webapps/birt-viewer/-" {
    permission java.security.AllPermission;
};

Configure Tomcat access

Edit /var/lib/tomcat5.5/conf/tomcat-users.xml and set up sensible access restrictions on your Tomcat install.

Mine looked like,

<?xml version='1.0' encoding='utf-8'?>
 <tomcat-users>
  <role rolename="tomcat"/>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="tomcat" password="PASSWORD" roles="tomcat,manager,admin"/>
  <user username="admin" password="PASSWORD" roles="tomcat,manager,admin"/>
 </tomcat-users>

Restart Tomcat and check that you can access the manager application - mine was at http://MYHOSTNAME:8180/manager/html/

Install BIRT to /var/lib/tomcat5.5/webapps

Download the BIRT runtime from http://download.eclipse.org/birt/downloads/

Unzip the BIRT runtime package you've downloaded, and move the birt-viewer directory to your Tomcat webapps dir.

unzip /tmp/birt-runtime-2_2_1_1.zip
sudo mv birt-runtime-2_2_1_1/WebViewerExample/ /var/lib/tomcat5.5/webapps/birt-viewer

Install MySQL JDBC drivers

Download the MySQL Connector/J JDBC drivers.

Copy the extracted driver .jar file to Tomcat.

NB: I thought these should be installed to /var/lib/tomcat5.5/shared/lib/ but my BIRT didn't run until I copied them to /var/lib/tomcat5.5/webapps/birt-viewer/WEB-INF/platform/plugins/org.eclipse.birt.report.data.oda.jdbc_2.2.1.r22x_v20070919/drivers/ - YMMV.

sudo cp mysql-connector-java-5.1.5-bin.jar /var/lib/tomcat5.5/webapps/birt-viewer/WEB-INF/platform/plugins/org.eclipse.birt.report.data.oda.jdbc_2.2.1.r22x_v20070919/drivers/

Enable BIRT

Visit your Tomcat manager page - mine was at http://MYHOSTNAME:8180/manager/html/

Ensure that the birt-viewer webapp is shown, and has started.

Click on the link to the birt-viewer app. You'll see a default test report, which will display a parameter from your URL.

Install your own reports
 |
Copy your own reports to the directory /var/lib/tomcat5.5/webapps/birt-viewer

Access them via URL like http://MYHOSTNAME:8180/birt-viewer/frameset?__report=MYREPORTFILE.rptdesign

Note that when creating reports in BIRT, the connection details need to be the same on the deployment server and the machine you develop the reports on. You could copy the database and database authentication to your desktop, although I simply created an SSH tunnel to make the live database "appear" at localhost on my desktop machine using,

ssh -f -N -L 3306:localhost:3306 MYHOSTNAME

You can change the connection parameters by editing the .rptdesign XML file, but the password is encoded in the file (BASE64?).