How to Install BIRT Viewer Runtime for Apache Tomcat in Linux

BIRT is an open source reporting engine that is based on Java technology. This is one of Eclipse top level project.

The following are two major components of BIRT:

1. BIRT Report Designer – You can design rich reports using this designer UI from Eclipse. The report design is stored in an XML format.
2. BIRT Viewer – This runtime viewer helps you to execute the report against any dataset. You can view the reports directly from Eclipse. Or, you can deploy the report as Apache Tomcat webapp, and view it from a web browser.

Birt Viewer helps developers to embed reports inside custom application. BIRT viewer supports various report output format including HTML, PDF, XLS, DOC, power point, postscript, etc.

This tutorial explains how to install BIRT viewer in Apache Tomcat environment.

1. Create Tomcat User

Before installing tomcat, create a Linux user where tomcat will be installed.

We’ll be deploying the BIRT runtime environment after Tomcat is installed.

adduser tomcat
passwd tomcat

2. Download Tomcat 8

Download the latest version of Apache tomcat from here.

Or, use wget to download it directly on the server as shown below.

su - tomcat

wget http://apache.osuosl.org/tomcat/tomcat-8/v8.0.15/bin/apache-tomcat-8.0.15.zip

unzip apache-tomcat-8.0.15.zip

3. Basic Tomcat Security Settings

Under the /home/tomcat/apache-tomcat-8.0.15/conf directory, locate the tomcat-users.xml file.

In this file, add the following two lines before “</tomcat-users>”

# vi tomcat-users.xml
  <role rolename="manager-gui"/>
  <user username="admin" password='mysecretpwd' roles="manager-gui"/>

4. Start Tomcat

Start the Apache Tomcat as shown below.

$ export CATALINA_HOME=/home/tomcat/apache-tomcat-8.0.15

$ cd $CATALINA_HOME/bin

$ sh catalina.sh start
Using CATALINA_BASE:   /home/tomcat/apache-tomcat-8.0.15
Using CATALINA_HOME:   /home/tomcat/apache-tomcat-8.0.15
Using CATALINA_TMPDIR: /home/tomcat/apache-tomcat-8.0.15/temp
Using JRE_HOME:        /usr
Using CLASSPATH:       /home/tomcat/apache-tomcat-8.0.15/bin/bootstrap.jar:/home/tomcat/apache-tomcat-8.0.15/bin/tomcat-juli.jar
Tomcat started.

Note: While starting the Apache tomcat if you are getting the following error message, make sure to install Java on your system.

# sh catalina.sh start
Neither the JAVA_HOME nor the JRE_HOME environment variable is defined
At least one of these environment variable is needed to run this program

On CentOS (or Red Hat), do the following to install java:

yum install java-1.8.0

Tomcat log messages are in this log file: $CATALINA_HOME/logs/catalina.out

5. Verify Tomcat Manager UI

Login to tomcat manager from the following URL:

http://{your-ip-address}:8080/manager/html

Enter the uid/pwd that you set in the tomcat-users.xml from one of the previous step.

In the Application section, you’ll see the following. At this time, you’ll not notice BIRT here:

• /
• /docs
• /examples
• /host-manager
• /manager

6. Download the BIRT Runtime Viewer

Go to BIRT download page, and locate this section “Latest BIRT Runtime Release Build” -> Click on “Download Now” from this section.

Or, use the wget to download it directly.

su - tomcat

wget http://mirrors.xmission.com/eclipse/birt/downloads/drops/R-R1-4_4_1-201409161320/birt-runtime-4_4_1-20140916.zip

6. Deploy BIRT Viewer

To deploy the BIRT Viewer, unzip the zip file and move the birt-runtime to the Tomcat webapps directory as shown below.

unzip birt-runtime-4_4_1-20140916.zip

cd birt-runtime-4_4_1

export CATALINA_HOME=/home/tomcat/apache-tomcat-8.0.15

cp -r WebViewerExample $CATALINA_HOME/webapps/birt-viewer

After that, view the catalina.out (tomcat log file), which will show that the birt-viewer is successfully deployed as shown below.

$ cd $CATALINA_HOME/logs

$ tail catalina.out
14-Nov-2014 22:17:41.937 INFO [localhost-startStop-2] org.apache.catalina.startup.HostConfig.deployDirectory Deployment of web application directory /home/tomcat/apache-tomcat-8.0.15/webapps/birt-viewer has finished in 24,050 ms

7. Verify Birt Viewer

Now, if you go to the following URL, you’ll see /birt-viewer in the list of application. You can click here to launch the viewer testing application.

http://{your-ip-address}:8080/manager/html

Or, you can directly go to the BIRT Viewer application as shown below.

http://{your-ip-address}:8080/birt-viewer/

As shown below, we’ve installed the latest version of the BIRT Viewer 4.4.1.

When you click on the “View Example”, it will launch the sample BIRT report that is bundled with the viewer as shown below.

This indicates that the BIRT runtime environment for viewer is setup and ready. You can start deploying your custom BIRT report xml file.