Skip to main content
Pentaho Documentation

Prepare Your Linux Environment for an Archive Installation

This article helps you to prepare your Linux environment for an archive installation. The archive process installs the Pentaho Server on a Tomcat web application server, which is provided by Pentaho. 

For installation of the Pentaho Server on an existing web application server, see Manual Installation of the Pentaho Server

Perform the following to prepare your Linux environment for an archive installation of the Pentaho Server:

  1. Create the Pentaho User.
  2. Create Linux Directory Structure.
  3. Install Java.
  4. Install the Pentaho Repository Host Database.
  5. Download and Unpack the Installation Files.
  6. Set Environment Variables.
  7. Advanced Linux Considerations.

Create the Pentaho User

Create a 'pentaho' user account that is assigned administrative privileges by performing the following steps:

  1. Create an administrative user on the computer which will host the Pentaho Server and name it 'pentaho'.
  2. Verify that you have the appropriate permissions to read, write, and execute commands in the pentaho user's home directory.
  3. Make sure your users can write to the directory where you install the Pentaho Server.

You will use this account to complete the rest of the installation instructions.

Create Linux Directory Structure

Choose an installation path. We recommend the following steps.

  1. Log on to the machine on which you will run the Pentaho Server. Make sure that you are logged on as the pentaho user.
  2. Create the following directory path from the 'Pentaho' home directory.
    <your home directory>/pentaho/server/pentaho-server
    <your home directory>/.pentaho
    
  3. Verify that you have the appropriate permissions to read, write, and execute commands in the directories you created.

Install Java

You must install a supported version of Java.

  1. Check the Components Reference to see which version of Java Pentaho supports.
  2. Download the supported version of the JRE or JDK from the Oracle site and install it. 

Install the Pentaho Repository Host Database

The Pentaho Repository houses data needed for Pentaho tools to provide scheduling and security functions. The repository also stores metadata and models for reports that you create. You can choose to host the Pentaho Repository on the following supported databases:

  • PostgreSQL
  • MySQL
  • Oracle
  • MS SQL Server

To install the Pentaho Repository's host database, complete the following steps.

  1. Check the Components Reference section to determine which versions of the databases Pentaho supports.
  2. Download and install the database of your choice. 
  3. Verify that the database is installed correctly.

Download and Unpack Installation Files

The Pentaho Server software, data files, and examples are stored in pre-packaged .zip files. You will need to manually copy these files to the correct directories.

Step 1: Download Files

Download the following installation and plugin files from the Pentaho Customer Support Portal.

  1. On the Customer Portal home page, sign in using the Pentaho support user name and password provided in your Pentaho Welcome Packet. 
  2. Click Downloads, then click Pentaho 7.1 GA Release in the 7.x list. 
  3. On the bottom of the Pentaho 7.1 GA Release page, click the Pentaho Server > Archive Build (Suggested Installation Method) folder in the Box widget and download each of the files listed below.  

Optionally, on the bottom of the Pentaho 7.1 GA Release page, click the Operations Mart folder in the Box widget and download the Pentaho Operations Mart .zip file. 

Component Zip File
Pentaho Server Installation File pentaho-server-7.1.0-dist.zip
Dashboard Designer Plugin pdd-plugin-ee-7.1.0-dist.zip
Interactive Reporting Plugin pir-plugin-ee-7.1.0-dist.zip
Pentaho Analyzer Plugin paz-plugin-ee-7.1.0-dist.zip
BA Operations Mart Files (optional) pentaho-operations-mart-7.1.0-dist.zip

Step 2: Unpack the Pentaho Server Installation File

  1. Unzip the Pentaho Server Installation file. Inside is the packaged installation file.
  2. Unpack the installation file by running the installer.sh. file.

If you are unpacking the file in a non-graphical environment, open a Terminal or Command Prompt window and type 'java -jar installer.jar -console' and follow the instructions presented in the window.​ 

  1. In the IZPack window read the license agreement, select I accept the terms of this license agreement, and then click Next.
  2. In the Select the installation path text box, browse to or enter the directory where you created the /pentaho/server/pentaho-server directory, and then click Next.
  3. A warning message that the directory already exists appears. Click Yes. Any existing files in the directory will be retained.
  4. When the installation progress is complete, click Quit.

Step 3: Unpack Plugin Files

Perform the following steps for each of the plugin files.

  1. To unpack the file, run the install.sh file. The IZPak window appears.

If you are unpacking the file in a non-graphical environment, open a Terminal or Command Prompt and type java -jar installer.jar -console and follow the instructions presented in the window.

  1. In the IZPak window, read the license agreement, select I accept the terms of this license agreement, and click Next.
  2. In the Select the installation path text box, enter the 'pentaho/server/pentaho-server/pentaho-solutions/system' directory, then click Next.
  3. A warning message that the directory already exists appears. Click Yes. Any existing files in the directory will be retained. 
  4. When the installation progress is complete, click Quit.

Step 4: (Optional) Unpack Operations Mart DDL Files

  1. ​To unpack the file, run the install.sh file. The IZPak window appears.
  2. In the IZPack window read the license agreement, select I accept the terms of this license agreement, and then click Next.
  3. In the Select the installation path text box, save the file in the pentaho/server/pentaho-server/data directory, and then click Next.
  4. A warning message that the directory already exists appears. Click Yes. Any existing files in the directory will be retained. 
  5. When the installation finishes, click Quit.
  6. Unzip the pentaho-operations-mart-ddl-7.1.0.zip file.  Move the directory for your database into pentaho/server/pentaho-server/data/<database name> and delete the others. The appropriate database names are shown in the following table:
If your Pentaho Repository is On:  Copy this directory into pentaho/server/pentaho-server/data/
PostgreSQL postgresql
MySQL mysql5
Oracle oracle10g
MS SQL Server sqlserver

Step 5: Verify Directory Structure

After you have finished unpacking all of the plugin and Pentaho Operations Mart files, the Pentaho directory structure should contain the following subdirectories:

  • pentaho/server/pentaho-server/pentaho-solutions/system/analyzer
  • pentaho/server/pentaho-server/pentaho-solutions/system/dashboards
  • pentaho/server/pentaho-server/pentaho-solutions/system/pentaho-interactive-reporting
  • pentaho/server/pentaho-server/
  • pentaho/server/pentaho-server/data/<database name>

The files extracted from the pentaho.war and pentah-style.war files will be located in the Pentaho\server\pentaho-server directory.

Set Environment Variables

Perform the following steps to set the PENTAHO_JAVA_HOME environment variable. 

  1. Set the path of the PENTAHO_JAVA_HOME variable to the path of your Java installation, as shown in the following example:
    export PENTAHO_JAVA_HOME=/usr/lib/jvm/java-8-oracle
    
  2. Log off and log on again. 
  3. Verify the variables have been properly set.

If you do not set these variables, Pentaho will not start correctly. 

If you are using a JRE, set the JRE_HOME home environment variable as well.

Advanced Linux Considerations

The following section is for Linux users who have a headless node.  There are two headless server scenarios that require special procedures on Linux system: 

  • A system which has no video card
  • A system which has a video card, but does not have an X server installed.

In some situations, particularly if your server does not have a video card, you will have to perform both procedures to properly generate reports with the Pentaho Server.

Systems without Video Cards

The java.awt.headless option enables systems without video output and/or human input hardware to execute operations that require them. To set this application server option when the Pentaho Server starts, you will need to modify the startup scripts for either the Pentaho Server or your Java application server.

While you do not need to do this step now, you will need to complete it prior to starting the Pentaho Server. At this point, add the following item to the list of CATALINA_OPTS parameters: '-Djava.awt.headless=true'. 

The entire line should look similar to the following:

export CATALINA_OPTS="-Djava.awt.headless=true -Xms4096m -Xmx6144m -XX:MaxPermSize=256m -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000"

If you intend to create a Pentaho Server service control script, you must add this parameter to that script's CATALINA_OPTS line.

Systems without X11

If you do not have an X server installed, you must complete these instructions.

To generate charts, the Pentaho Reporting engine requires functions found in X11. If you are unwilling or unable to install an X server, you can install the xvfb package instead. The xvfb package provides the X11 framebuffer emulation, which performs all graphical operations in the memory rather than sending them to the screen.

Use your operating system's package manager to properly install the xvfb package.

Next Step

Once you have finished preparing your environment, you can configure your repository database. Select the database that you are using as the solution repository: