Skip to main content
Hitachi Vantara Lumada and Pentaho Documentation

Prepare Your Linux and Mac Environment for Installation

Create the Pentaho User

Create a pentaho user account that has administrative privileges.  You will use this account to complete the rest of the installation instructions.

  1. Create an administrative user on computer that will host the BA 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.

Install the BA Repository Host Database

The BA 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 BA Repository on these databases.

  • PostgreSQL
  • MySQL
  • Oracle
  • MS SQL Server

To install the BA Repository's host database, do these things.

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

Install Java 

Install a supported version of Java.

  1. Check the Supported Technologies list 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.

Unpack BA Server Installation File

  1. Unzip the BA Server Installation file.
  2. To unpack the file, run  The IZPak window appears.
  3. Read the license agreement, select I accept the terms of this license agreement, and click Next.
  4. In the Select the installation path text box, enter the place where you want to create the pentaho directory, then click Next.
  5. A message indicating that a target directory will be created appears.  Click Yes.
  6. When the installation progress is complete, click Quit.
  7. Navigate to the pentaho directory and create a server subdirectory.
  8. Move the biserver-ee directory into the server directory.  When you are finished, the directory structure should look like this:
    • pentaho/jdbc-distribution
    • pentaho/license-installer
    • pentaho/server/biserver-ee

Set Environment Variables

Set the PENTAHO_JAVA_HOME  and PENTAHO_INSTALLED_LICENSE_PATH environment variables. 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.

  1. Set the path of the PENTAHO_JAVA_HOME variable to the path of your Java installation, like this.
    export PENTAHO_JAVA_HOME=/usr/lib/jvm/java-7-sun
  2. Set the path of the  PENTAHO_INSTALLED_LICENSE_PATH variable to the path of your installed licenses, like this.
    export PENTAHO_INSTALLED_LICENSE_PATH=/home/pentaho/.pentaho/.installedLicenses.xml
  3. Log out and in again, then verify the variables have been properly set.

Advanced Linux and Mac Topics

Complete the instructions in this section only if you have a headless node or if you plan to install on a Mac OS.

Prepare a Headless Linux or Solaris Server

There are two headless server scenarios that require special procedures on Linux and Solaris systems. One is for a system that has no video card; the other is for a system that has a video card, but does not have an X server installed. In some situations -- particularly if your server doesn't have a video card -- you will have to perform both procedures to properly generate reports with the BA 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 BA Server starts, you will need to modify the startup scripts for either the BA Server, or your Java application server. You do not need to do this now, but you will near the end of these instruction when you perform the Start BA Server step. For now, add the following item to the list of CATALINA_OPTS parameters: -Djava.awt.headless=true.

The entire line should look something 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 BA Server service control script, you must add this parameter to that script's CATALINA_OPTS line.

If you do not have an X server installed, you must also follow the below instructions.

Systems without X11

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

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

Adjust Amount of Memory Mac OS Allocates for PostgreSQL

If you plan to install the software on a Mac OS, and you choose to use PostgreSQL, you need to increase the amount of memory that the Mac OS allocates for PostgreSQL. You can skip these instructions if you plan to install the software on Windows or Linux.

PostgreSQL is the name of the default database that contains audit, schedule and other data that you create.  PostgreSQL starts successfully only if your computer has allocated enough memory. Go to and follow the instructions there on how to adjust the memory settings on your computer. 

Next Step

You've finished preparing your environment.  Go to Configure Your Repository Database to continue.