Skip to main content
Pentaho Documentation

Prepare your Linux environment for an archive install

Parent article

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.

Process overview

You will perform the following steps to prepare your Linux environment for an archive installation of the Pentaho Server. This process includes setting up the correct directory structure, ensuring proper tools are in place, and then downloading and unpacking the Pentaho installation files.

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

Create the Pentaho user

Create an account that is assigned administrative privileges by performing the following steps. You will use this account to complete the rest of the installation instructions.

  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 suite.

Create Linux directory structure

Choose an installation path for installing Pentaho on a Linux system. Pentaho recommends the directories and subdirectories listed in this topic.

  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

To install Pentaho, you will need to 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 website 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.

Before you begin

Choose which type of database to use for the Pentaho Repository's host database, then install it. Pentaho supports these databases:
  • PostgreSQL
  • MySQL
  • Oracle
  • MS SQL Server

Procedure

  1. Check the Components Reference to section to determine which versions of the databases Pentaho currently 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 software and some of its components are delivered in compressed files that need to be unpacked prior to starting the Pentaho archive installation process.

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

The first step for an archive installation of the Pentaho system is to download the compressed files that contain the software.

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

Procedure

  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 Pentaho8.3 GA Release in the 8.x list.

  3. At the bottom of the Pentaho 8.3 GA Release page, click the Pentaho Server folder and then click the Archive Build (Suggested Installation Method) folder in the Box widget and download each of the files listed below.

    ComponentZIP File
    Pentaho Server Installation Filepentaho-server-ee-8.3.0-dist.zip
    Dashboard Designer Pluginpdd-plugin-ee-8.3.0-dist.zip
    Interactive Reporting Pluginpir-plugin-ee-8.3.0-dist.zip
    Pentaho Analyzer Pluginpaz-plugin-ee-8.3.0-dist.zip
    BA Operations Mart Files (which are optional)pentaho-operations-mart-8.3.0-dist.zip
    Note(Optional) On the bottom of the Pentaho 8.3 GA Release page, click the Operations Mart folder in the Box widget and download the ZIP file named: Pentaho Operations Mart.

Step 2: unpack the Pentaho Server installation file

The Pentaho Server installation file is a package file and needs to be unpacked.

Perform the following steps to unpack the Pentaho Server installation file.

Procedure

  1. Unzip the Pentaho Server installation file to a folder.

  2. Run the install.sh file to unpack the installation file.

    The IZPak window appears.
    NoteIf 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.​
  3. Read the license agreement in the IZPack window.

    1. Select the I accept the terms of this license agreement check box

    2. Click Next.

  4. 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.

    A warning message appears informing you that the directory already exists.
  5. Click Yes.

    Any existing files in the directory will be retained.
  6. Click Quit when the installation progress is complete.

Step 3: Unpack plugin files

Since the plugin files are package files, they must be unpacked.

  1. Unzip the plugin file to a folder.

    The packaged installation file is in the folder.
  2. Run the install.sh file to unpack the installation file.

    The IZPak window appears.
    NoteIf 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.
  3. Read the license agreement in the IZPack window. Select the I accept the terms of this license agreement check box, and then click Next.

  4. In the Select the installation path text box, enter the pentaho/server/pentaho-server/pentaho-solutions/system directory, then click Next.

    A warning message appears informing you that the directory already exists.
  5. Click Yes.

    Any existing files in the directory will be retained.
  6. Click Quit when the installation progress is complete.

Step 4: (Optional) unpack Operations Mart DDL files

The Pentaho Operations Mart distribution file is a package file and needs to be unpacked.

  1. Unzip the Pentaho Operations Mart distribution file to a folder.

    The packaged installation file is in the folder.
  2. Run the install.sh file to unpack the installation file.

    The IZPak window appears.
  3. Read the license agreement in the IZPack window. Select the I accept the terms of this license agreement check box, and then click Next.

  4. In the Select the installation path text box, enter the pentaho/server/pentaho-server/data directory, then click Next.

    A warning message appears informing you that the directory already exists.
  5. Click Yes.

    Any existing files in the directory will be retained.
  6. Click Quit when the installation progress is complete.

  7. Unzip the pentaho-operations-mart-ddl-8.3.0.zip file.

  8. 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/
    PostgreSQLpostgresql
    MySQLmysql5
    Oracleoracle10g
    MS SQL Serversqlserver

Step 5: verify directory structure

After you have finished unpacking all the plugin and Pentaho Operations Mart files, the newly created Pentaho directory structure should contain these pentaho directories and subdirectories.

  1. Verify that the Pentaho files are placed in the correct locations by comparing the pentaho directory structure, as shown, with yours.

    • 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>

Set environment variables

If you do not set the HOME environment variables, Pentaho will not start correctly. Complete the steps in this topic to ensure that you have set the HOME environment variables properly.

  1. Set the path of the PENTAHO_JAVA_HOME variable to the path of your Java installation, as shown:

    export PENTAHO_JAVA_HOME=/usr/lib/jvm/java-8-oracle
  2. (Optional) If you are using a JRE, then also set the JRE_HOME home environment variable.

  3. Log off and log on again, then verify the variables have been properly set.

Advanced Linux considerations

There are two headless server scenarios that require special procedures on a Linux system.

The two headless node scenarios are:
  • 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 parameter enables systems without video output and/or human input hardware to execute operations that require them. To set this application server option to be applied at every Pentaho Server startup, you will need to modify the startup scripts for either the Pentaho Server or your Java application server.

Prior to starting the Pentaho Server the first time, add the -Djava.awt.headless=true parameter to the list of CATALINA_OPTS parameters. The entire line should look like this:
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 same parameter to that script's CATALINA_OPTS line.

Systems without X11

To generate charts, the Pentaho Reporting engine requires functions found in X11. This topic is for Linux users who have a headless node and a video card, but do not have an X server installed.

If you are unwilling or unable to install an X server, you can install the Xvfb package instead. Xvfb 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 Xvfb.

Prepare your Pentaho Repository

Once you have finished preparing your environment, you can initialize and configure your Pentaho Repository.

Select the database that you are using as your Pentaho Repository: