Contents 1 Installing Pentaho 1.1 Installing Tomcat 1.1.1 Overview 1.1.2 Configuration 1.2 Installing Pentaho on Tomcat 1.2.1 Configuring email

Installing Pentaho

Installing Tomcat

apt-get install tomcat6 tomcat6-examples tomcat6-docs tomcat6-admin

Add manager and admin role to /etc/tomcat6/tomcat-users.xml, add user to manager & admin roles with password for authentification.

Tomcat instance is on http://localhost:8080 by default, there are also http://localhost:8080/examples/ and http://localhost:8080/docs/. You can check your Tomcat installation by using the examples webapp.

Tomcat will be launched at start-up via /etc/init.d/tomcat6

Overview

Tomcat is an important common element of Pentaho and JasperReports, and it's worth documenting how it works.

Tomcat is basically a web server which allows the server-side execution of Java code in one of a number of ways:

1. Servlets are Java objects which are instantiated on the server and which can conserve state across user sessions, and handle HTTP queries
2. JSP pages allow Java code to be embedded directly in web pages (similar to PHP). JSPs are precompiled into servlets by the server.
3. Taglibs allow the developer to define custom tags which will be parsed on the server and will run predefined methods of specific classes when they are used. Similar to JSPs, custom tags are pre-compiled in JSPs to instantiate and call the classes which handle them.

Tomcat thus requires a way to compile JSPs into Java code into .class files - this component of Tomcat is called Jasper. Tomcat has two other important components: the Coyote HTTP server parses HTTP traffic, and Catalina, its servlet container instantiates and stores classes in memory on the server.

Recent versions of Tomcat no longer include the JSP Standard Taglib Library by default. You will need to download and install JSTL from Apache to make all of the examples work correctly - these are also required for Pentaho.

Configuration

Tomcat is typically started via an init script, /etc/init.d/tomcat6, which initiates the following environment variables:

CATALINA_HOME

the directory where the Tomcat binary, class files and any common JAR files are found

CATALINA_BASE

The directory where Catalina will generate class files and use as the base directory for any deployed webapps

JAVA_HOME and JAVA_OPTS

Environment variables for the system JRE (or JDK) install

Finally, the init shell will call catalina.sh in $CATALINA_HOME/bin to start the servlet engine.

On starting Catalina, a number of config files will be read, in the following order, and in the following places:

In $CATALINA_BASE/conf, the files catalina.policy, catalina.properties, logging.properties, content.xml, server.xml, tomcat-users.xml and web.xml are parsed:

catalina.policy

defines the global security policy for the server

catalina.properties

server-wide configuration

logging.properties

defines various logging-related options

content.xml

Defines Tomcat Context information. A Context is a single web application running inside Tomcat. Context can be defined in a number of ways:

• $CATALINA_BASE/conf/context.xml - contexts defined here have their elements loaded by all webapps
• $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml.default
• XML files in $CATALINA_BASE/conf/[enginename]/[hostname] - each XML file defines a new context path - examples.xml defines the context path "/examples"
• /META-INF/context.xml files inside .war files - these files *should* get copied to $CATALINA_BASE/conf/[enginename]/[hostname]
• Finally a Context element inside a Host element in conf/server.xml - since other methods provide a means for simple per-webapp contexts, this method should be avoided.

server.xml

The global configuration file - defines hosts, contexts, and more. Analogous to httpd.conf for apache.

tomcat-users.xml

Contains information about users, passwords and trusted Realms on the server

web.xml

Options and values which will be shared by all webapps. Each webapp also has a context-specific config file in WEB-INF/web.xml

Installing Pentaho on Tomcat

The best guide I found for this is here: https://docs.google.com/Doc?docid=0AdJmocc0fj_EZDJ3YmZiZF83M2RtaHhwcmRk&hl=en

1. Install Sun's Java and Tomcat, and get them working. On Ubuntu, this will set CATALINA_HOME to /usr/share/tomcat6 and CATALINA_BASE to /var/lib/tomcat6, and ${CATALINA_BASE}/conf is a sym link to /etc/tomcat6.
2. Download and unpack pentaho-ce-3.7.0.stable.tar.gz from sourceforge
3. Move biserver-ce and administration-console to /opt/pentaho (or /var/lib/pentaho, wherever you want to install it - for the rest of the document, we'll refer to this as PENTAHO_HOME)
4. Copy (if it's not already there) mysql-connector-java-5.0.7.jar from biserver-ce/tomcat/common/lib to $CATALINA_HOME/lib
5. Copy pentaho, pentaho-styles and sw-styles webapps from biserver/tomcat/webapps/ to $CATALINA_BASE/webapps
6. Move biserver-ce/pentaho-solutions to $PENTAHO_HOME
7. Create the required Pentaho databases (quartz, hibernate and sample_datasource) complete with database users, by downloading and executing in order these SQL scripts. Apparently the sample data delivered with pentaho-ce is lacking in some way, but I don't understand how. You should change the passwords for hibuser and pentaho_user in these scripts to something better than 'password' before running them.

Once you have the databases, you need to configure them as data sources for the Pentaho web application. This has several aspects:

1. Setting the JDBC security to use a MySQL database instead of the packages Hypersonic database (I'll admit, I really don't understand this) - this document has details for changes needed
   1. applicationContext-spring-security-jdbc.xml in pentaho-solutions/system/: change driver to mysql & password for hibuser
   2. applicationContext-spring-security-hibernate.properties in pentaho-solutions/system/:change driver to mysql & password for hibuser
   3. hibernate-settings.xml in pentaho-solutions/system/hibernate: change config file to point to MySQL settings
   4. mysql5.hibernate.cfg.xml in pentaho-solutions/system/hibernate: change password for hibuser
2. Configure the hibernate and quartz databases for use with the webapp
   1. Update the context.xml file which should be present (if you used the biserver-ce package, not the -manual one) in $CATALINA_BASE/webapps/pentaho/META-INF/ to use the MySQL JDBC driver (and set the password correctly for hibuser and pentaho_user)
3. Configure the sampledata database for use as a data source: In the hibernate database, update the DATASOURCE table to set DRIVERCLASS, URL and QUERY to the appropriate values when the NAME is SampleData. If you change the password for the pentaho_user user from 'password', you will need to do the same for the SampleData datasource, which will require you to launch the administration panel. To do this, you first need to configure the panel to set the path to the pentaho-solutions directory and the pentaho webapp in $PENTAHO_HOME/administration-console/resource/config/, then run start_pac.sh in $PENTAHO_HOME/administration-console and connect to http://localhost:8099 (username/password is 'admin'/'password' by default)

Finally, we need to configure the Pentaho application for the local set-up:

1. In $CATALINA_BASE/webapps/pentaho/WEB_INF/web.xml: Set the solutions-path parameter to $PENTAHO_HOME/pentaho-solutions
2. Set fully-qualified-server-url to the name of the server, port and path for the webapp (eg. http://localhost:8080/pentaho) - if you want people to be able to use Pentaho remotely, this should be an IP address or hostname, rather than localhost (since it's the URL used internally to find resources)
3. Disable startup of Hypersonic by commenting the relevant sections (hsqldb-databases and the appropriate listener)
4. Add trusted connecting hosts to TrustedIpAddrs (I used a netmask: 192.168.1.0/255.255.255.0)

Finally, ensure that you have set permissions correctly for the Tomcat user on $PENTAHO_HOME/pentaho-solutions and $CATALINA_BASE/webapps/pentaho - the webapp needs write access there.

Now restart Tomcat, and go to http://localhost:8080/pentaho to see if it's working.

Configuring email

To send email from reports, you can configure smtp in pentaho-solutions/system/smtp-email/email_config.xml - there is a sample config file for GMail which you can copy over, if you use gmail SMTP, in email_config_gmail.xml - all you need to do is set your username, the email address which will appear in the "From:" header, and your password.