Skip to main content
Pentaho Documentation

Prepare Environment


Explains how to prepare your environment for the installation of Pentaho software.


This task explains how to prepare your computer for the installation of the software.

Create User Account

Windows User Account

If you plan to install the Pentaho BA Suite on a computer that runs Windows, you do not need to create a special user account. Just make sure that you have the appropriate privileges needed to install software. Often, this means that you need administrative-level privileges for the account that you use to install the software. Some Windows systems have expanded user access and permissions restrictions that change the way the software is installed and accessed by system users. If this happens, the installation wizard will require that you execute it with elevated permissions (Run Elevated status) so that the BA and DI Servers are accessible to all users.

Linux User Account

If you plan to install the software on a computer that runs Linux, create a user account named pentaho on the computer.

  1. Open a Terminal window on the server on which you plan to install the software. If you plan to install the software on a remote computer, establish an OpenSSH session to the remote server.
  2. In the Terminal window, log in as the root user by entering this command at the prompt.
    su root
  3. When prompted, type the password in the Terminal window.
  4. In the Terminal window, create a new user account called pentaho, along with the pentaho home directory, by typing this line.
    sudo useradd -s /bin/bash -m pentaho
    Note: /bin/bash indicates that the user account should be created using the Bash shell. In many Linux distributions, the default new user shell is /bin/sh or some equivalent, such as Dash, that might not use the ~/.bashrc configuration file by default. If you don't have or want to use Bash, adjust the instructions throughout this section accordingly.
  5. In the Terminal window, assign a password for the pentaho user by typing this line.
    sudo passwd pentaho
  6. Verify that you can log in using the newly-created pentaho user account.
    1. In the Terminal window, log in by typing this command.
      su pentaho -
    2. Type the password for the pentaho user account if you are prompted.
    3. Use the Terminal window to navigate to the pentaho directory to verify that it has been created. By default, it is in the /home directory.
    4. Close the Terminal window.

Disable Anti-Spyware and Anti-Virus Programs

Disable any anti-spyware and anti-virus software before installing Pentaho Business Analytics. Some types of software firewalls and anti-virus scanners may also block the BA Server or prevent it from operating normally. After the server is installed, renable them.

Advanced 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 in order 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.

Note: 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.