This page will guide you through the process of installing the Pentaho Report Designer Community Edition.

In addition it also covers any additional optional steps needed to install extra fonts. Finally I will explain how to configure the Pentaho Reporting Engine and the Pentaho Report Designer.

0. Prerequisites

The Pentaho Reporting Engine requires Java 1.5.0 installed on your system. The Java Runtime environment used must be fully compliant to the Java standard.

The Pentaho Report Designer requires at least JDK 1.6.0.

GNU GCJ, the standard java environment used in Red Hat Linux will NOT work, as it does not implement critical parts of the Java standard API. We have no information how good the other free Java implementations follow the standard, and therefore we cannot make any guarantees on them.

Where ever possible use a standard conforming Java Runtime System. The Sun/Oracle JDK, OpenJDK and the IBM JDKs are known to work flawlessly.

Windows:

The Oracle Java Runtime can be downloaded from Java.com.

Ubuntu Linux 10.4:

Install the package "openjdk-6-jdk" and then update the internal configuration links to always use the OpenJDK as default.

sudo apt-get install sun-java6-jdk
sudo update-alternatives --config java

Ubuntu Linux 9.10 or older; Debian Stable (lenny)

Install the package "sun-java6-jdk" and then update the internal configuration links to always use Sun's JDK as default.

sudo apt-get install sun-java6-jdk
sudo update-alternatives --config java

SuSE Linux

Install the package "java-1_6_0-openjdk" via YaST.

Fedora Linux

Install the package "java-1.6.0-openjdk".

MacOS-X

Every Mac comes with a pre-installed Java Runtime environment. You are perfectly prepared.

1. Download the Pentaho Report Designer

The various versions of Pentaho Report Designer can be downloaded from the JFreeReport project on Sourceforge

2. Installation

The Pentaho Report Designer download is a archive file that needs to be extracted before the report designer can run. Use your operating system's unzip tool to extract the report-designer and run either the *.bat (Windows) or *.sh (Linux) file.

During the first start the Pentaho Report Designer will initialize the local configuration in $HOME/.pentaho.

Windows

Unzip the downloaded ZIP-archive by double clicking on it.
Copy the "report-designer" directory from the ZIP file to your "Program Files" directory.
You can start the Pentaho Report Designer with the "report-designer.bat" file.

Linux (all versions)

After downloading the tar.gz or zip file, extract the contents.

tar -zxf prd-ce-3.7.0-stable.tar.gz

or

unzip prd-ce-3.7.0-stable.zip

This will create a "report-designer" directory.

Within the report-designer directory, execute "report-designer.sh" to launch the Pentaho Report Designer.

The report-designer must be run from within your X11-environment (for instance a XTerm window). It cannot be run from a text-console. Make sure that you have a Java 1.6.0 Runtime installed.

MacOS-X

After the download is complete, you will find the download archive in your "Downloads" folder.
Extract the contents of the downloaded file. To extract the file, double click on the file in the Finder.
Drag the Report Designer into /Applications

4. Installing database drivers

Pentaho Reporting requires JDBC drivers to communicate with the database system. Each database vendor should provide suitable drivers for their databases. If your database vendor does not provide JDBC drivers, it may be possible to use ODBC drivers via the JDBC-ODBC bridge driver that comes with the JDK. However, in most cases, such connections suffer from various bugs in the underlying driver system. If your database does not support JDBC access and the ODBC drivers do not work properly, then Pentaho Reporting is not able to access your data.

Your only option would be to switch to a different database or a different reporting product.

Installing JDBC drivers is simple. Copy the driver, in many cases a *.jar file, into the "lib/jdbc" directory within Pentaho Report Designer's installation directory. If you are using the Pentaho BI-Server, you will also have to install the same driver into the BI-Server's application server.

Suitable drivers for MySQL, H2 and HypersonicSQL are already included in the download.

Downloading Drivers

DatabaseURL

Oracle	http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html
MS-SQL-Server	http://msdn.microsoft.com/en-us/sqlserver/aa937724.aspx or http://jtds.sourceforge.net/
PostreSQL	http://jdbc.postgresql.org/

5. (Optional) Configuring JNDI data sources

When storing the data source connection information inside the report can cause severe maintainability problems later. Each report contains its own copy of the connection information. If that information changes (for example if the database moves to a different host), all reports referencing that database must be changed manually.

In many companies report designer also do not have access to the databases that store the real data. To make sure that reports can be moved safely from the development environment to the testing environment, the data source information must be stored outside of the report.

JNDI is a method of separating data source configuration information from the actual use of the data source. Each data source has a unique name, under which the reporting engine can find the actual connection. A JNDI provider (usually part of a application infrastructure) manages all data sources and is responsible for connecting to the database.

Within the Pentaho Report Designer, you can define your common data sources in a local configuration file. The JNDI configuration for the Pentaho Report Designer is stored "$HOME/.pentaho/simple-jndi". Editing the contents of "report-designer/configuration-template/simple-jndi" has no effect, as the report designer is not using that directory at runtime.

The Pentaho BI-Server uses its own configuration. You can edit the BI-Server's configuration via the BI-Server's Administration Console.

Within the "simple-jndi" directory, edit a file called "default.properties", which should list all your data sources.

The general template for a data source definition is:
(text written in italics need to be replaced with suitable values)

name/type=javax.sql.DataSource
name/driver=database driver
name/user=database username
name/password=database password
name/url=jdbc-url

Additional properties can be passed by adding more property-name and property-value pairs.

name/property-name=property-value

Example:

SampleData/type=javax.sql.DataSource
SampleData/driver=org.hsqldb.jdbcDriver
SampleData/user=pentaho_user
SampleData/password=password
SampleData/url=jdbc:hsqldb:mem:SampleData

6. (Optional) Configuring Logging

Pentaho Reporting uses Log4J as common log system. All errors and other status information is logged using this system. If you encounter errors or want to fine tune your reports, you may find helpful detail information in these logs.

By default, Pentaho Reporting only logs to the console.

Logging can be configured by editing the "log4j.xml" file in Pentaho Report Designer's "resources" directory. Please see the Log4J wiki for more information on Log4J and the log4j configuration format.

Log4J Documentation
Log4J Example configuration in the Log4J Wiki

7. (Optional) Global configuration

The Pentaho Reporting Engine inside the Pentaho Report Designer can be configured by placing a 'classic-engine.properties' file into $PRD/resources.

The configuration contains both global and locale settings

Global settings apply to all reports and usually configure a system wide default or control behaviour that applies to the whole system (like caches, or parser configurations).

Local settings configure report specific behaviour, like text encodings or export target settings. Local settings can be configured from within the Pentaho Report Designer.

For Pentaho Reporting, the main configuration resides in two files. You can find all of these files in $PRD/resources. These files are properties files that contain name-value pairs.

See: http://en.wikipedia.org/wiki/.properties

classic-engine.properties file

This file contains the configuration for the reporting engine. The most notable use is to configure default values for the report-environment.

report-designer.properties file

This file contains the report designer configuration. It can be used to provide default credentials for the Pentaho Publish feature which allows you to publish reports to a running Pentaho BI-Server.

8. Installing additional Fonts

Pentaho Reporting uses fonts to display text inside reports. When generating PDF files, the Pentaho Reporting Engine needs access to the physical font files. The reporting engine searches system dependent font paths to locate all usable fonts. In addition to these fonts, your Java Runtime Environment may offer additional fonts, depending on your Java and Operating system version .

If you plan to create PDF documents with embedded fonts, please ensure that you only use fonts that are physically accessible for the reporting engine.

Regardless of your operating system, all font files located in $JRE/lib/fonts are always usable for all exports.

Further information can be found in the [internationalization guide of the JDK |http://download.oracle.com/javase/1.3/docs/guide/intl/addingfonts.html#adding]

Linux/Unix

The reporting engine will register all fonts found in the directory "/usr/X11R6/lib/X11/fonts" and all its subdirectories. Additionally the directory "/usr/share/fonts" is searched for usable font files.

On some older Linux systems, the Java Runtime does not use fonts installed in the X11-Server. If your Pentaho Report Designer lacks fonts which other Linux Applications have copy your font files into the "$JRE/lib/fonts" directory.

Modern versions of the Java Runtime Environment that run on more recent Linux versions should not show these problems any more.

MacOS

For MacOS X these font directories are searched in the following order:

~/Library/Fonts
/Library/Fonts
/Network/Library/Fonts
/System/Library/Fonts

Any font that conforms to the Windows TrueType font standard can be used by Pentaho Reporting. Some fonts shipped with older versions of MacOS-X lack some critical internal data tables and cannot be used by the Pentaho Reporting Engine.

The Java Runtime should use all these fonts

Windows

The "Windows/fonts" directory is used to locate and register the system fonts. The JDK uses all fonts that are available, no additional work is needed.

Increasing the memory available for reporting

By default the Pentaho Report Designer uses 512MB of RAM to generate reports. This is plenty of space for the majority of the reports generated. However, some database drivers and data-sources use a large amount of memory for their own purposes, so that it may be necessary to increase the overall memory that is available for the reporting system.

Windows

To increase the memory, edit the "report-designer.bat" file. Locate the following line:

start "Pentaho Report Designer" "%_PENTAHO_JAVA%" -XX:MaxPermSize=256m -Xmx512M -jar "%~dp0launcher.jar" %*

and change the portion that reads "-Xmx512M" to a higher value. To set the maximum memory to 800MB, set this value to "-Xmx800M". If you use a 32-Bit version of Windows, most Java
Runtime implementations are limited to about 1GB (1024MB) of usable memory. If you try to allocate to much memory, starting the Pentaho Report Designer will fail with an error.

64-Bit Versions of Java running on a 64-Bit Windows do not suffer from this limitation.

Linux

To increase the memory, edit the "report-designer.sh" file. Locate the following line:

"$_PENTAHO_JAVA" -XX:MaxPermSize=512m -jar "$DIR/launcher.jar" $@

and change the line so that it reads

"$_PENTAHO_JAVA" -XX:MaxPermSize=512m -Xmx1024M -jar "$DIR/launcher.jar" $@

Adjust the number on the -Xmx parameter to a suitable value. Do not allocate more than your physically available memory. A good rule of thumb is to leave 1GB to your operating system and the other services. So if you have a 4GB machine, the maximum memory you could safely allocate would be 3072MB (3GB).

MacOS

The Pentaho Report Designer on MacOS reads its memory settings from the application bundle's "info.plist" file.

(1) Locate the report designer application in your finder.
(2) Right click (or CTRL-click) on the application to open the context menu. Select "Show Package Contents"
(3) Locate the file "Contents/info.plist" and edit it with the text-editor.
(4) Locate the lines that read

<key>VMOptions</key>
<string> -Xms256m -Xmx512m</string>

Adjust the number on the -Xmx parameter to a suitable value. Do not allocate more than your physically available memory. A good rule of thumb is to leave 1GB to your operating system and the other services. So if you have a 4GB machine, the maximum memory you could safely allocate would be 3072MB (3GB).

Additional Installation Documentation

Running Report Designer with Self-Signed Certificates