Skip to main content
Pentaho Documentation

Prepare Environment

Overview

Explains how to prepare your computers for installation.

Image of the BA Manual installation steps.

Overview

To prepare the computer on which you plan to install the BA Server, complete these tasks.

Create User Account

Create Windows User Account

If you plan to install on a server that runs Windows, you do not need to create a special user account on the server. However, you should use an account that has administrator privileges to complete the tasks in these instructions.

Create Linux User Account

If you plan to install the BA Server in a Linux environment you must create a user account named pentaho on the server computer. By default, license information for Pentaho products is stored in the home directory for this account. Use this account to perform installation tasks that do not require root access. Also, use this account to run start and stop server scripts.

  1. Open a Terminal window on the server. If you plan to install the BA Server on a remote computer, establish an OpenSSH session to the remote server.
  2. In the Terminal window, log in as the root user by typing this command.
    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 in 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, attempt to log in by typing this line.
      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.

Create Directory Structure

Create Windows Directory Structure

  1. Log into the machine on which you will run the BA Server.
  2. Create this directory path.
    
    pentaho\server\biserver-ee
    
    
  3. Verify that you have the appropriate permissions to read, write, and execute commands in the directories you created.
    1. Open Windows Explorer and right-click the pentaho directory.
    2. Select the Properties option and the Security tab to verify that you have read, write, and execute permissions.
    3. In Windows Explorer navigate to server directory, then right-click.
    4. Select the Properties option and the Security tab to verify that you have read, write, and execute permissions.
    5. In Windows Explorer and navigate to the biserver-ee directory and right-click it.
    6. Select the Properties option and the Security tab to verify that you have read, write, and execute permissions.

Create Linux Directory Structure

  1. Log into the machine on which you will run the BA Server. Make sure that you are logged in as the pentaho user.
  2. Create this directory path from home directory (pentaho).
    <your home directory>/pentaho/server/biserver-ee
    <your home directory>/.pentaho
    
  3. Verify that you have the appropriate permissions to read, write, and execute commands in the directories you created.
    1. In Linux check the permissions of the pentaho, server, and biserver-ee directories by opening a Terminal window, navigating to the pentaho directory, then typing this command.
      ls -ld ../.pentaho ../pentaho ../pentaho/server ../pentaho/server/biserver-ee
      
    2. Make sure that permissions for the directories allow you to read, write, and execute in those directories.

Install the Web Application Server

The BA Server can be deployed on either the Tomcat or JBoss web application server. By default, BA Server software is configured for Tomcat. This means that if you choose to use Tomcat, you will need to make fewer configuration changes than you would if you choose to use JBoss.

You must install the web application server yourself. If you already have a Tomcat or JBoss web application server installed and you want to deploy the BA Server on it, please skip this step.

  1. To download and install the web application software, use the instructions in the documentation for the web application server of your choice. We recommend that you install the web application server in the pentaho/server/biserver-ee directory.
  2. Verify the web application server is installed correctly by starting it and viewing the default page. If the web application server does not start, troubleshoot it using the web application server's documentation before you continue with the BA Server installation process.
  3. Stop the web application server.

Install the BA Repository Host Database

The BA Repository houses data needed for Pentaho tools to provide scheduling and security functions, as well as metadata and models for reports that you create.

You can choose to host the BA Repository on the PostgreSQL, MySQL, or Oracle database. By default, Pentaho software is configured to use the PostgreSQL Database. If you already have a BA Repository database installed, you can skip this step. To install for the host database for the BA Respository, do these things.

  1. To download and install the BA Repository database, use the instructions in the documentation for the database of your choice. It does not matter where you install the database.
  2. Verify that the BA Repository database is installed correctly. You can do this by connecting to your database and viewing the contents of any default databases that might have been created upon installation. Consult the user documentation for the database that you installed for further details. Note: If you are not familiar with SQL, consider using a visual database design tool to connect to the database and view its contents.
    • PGAdminIII is bundled with PostgreSQL.
    • MySQL Workbench can be used with MySQL. It is available as a separate download. Check the MySQL site for details on how to obtain this design tool.
    • Oracle SQL Developer can be used with Oracle. It is available as a separate download. Check the Oracle site for details on how to obtain this design tool.

Install Java JRE or JDK

Make sure that the version of the Java Runtime Environment (JRE) or the Java Development Kit (JDK) that Pentaho needs to run is installed on your system. You do not need to uninstall other versions of Java if you already have them running on your system. These instructions explain how to check for your default version of Java that is running on your computer and where to get the required version if you need one.

  1. Check the supported technologies list to see which version of the JRE or JDK is needed for the software.
  2. If you have not done so already, log into the computer on which you plan to install the software. Ensure that you have the appropriate permissions to install software.
  3. Open a Terminal or a Command Prompt window. Enter this command.
    java -version
    
  4. If the version of Java does not match the version needed to run Pentaho software, check your system to see if there are other versions of Java installed.
  5. If the version of Java that you need to run Pentaho software is not on your system, download it from the Oracle site and install it.

Download and Unpack Installation Files

If you want to install specific Pentaho software, obtain the installation packages from the Pentaho Customer Support Portal. Consult your Welcome Kit if you need more information about the portal. The Pentaho BA Server software, data files, and examples are stored in pre-packaged .war and .zip files. Manually copy these files to correct directories.

Note: These instructions explain how to install the BA Server only. If you want to install the plugins, finish installing the BA Server, then see Install Only BA Tools.
  1. Make sure the web application server on which you plan to deploy the BA Server has been stopped.
  2. Download the biserver-manual-ee-5.2.0-dist.zip file from the Pentaho Customer Support Portal.
  3. Unpack the file by completing these steps.
    1. Use a zip tool to extract the distribution files you just downloaded.
    2. Open a Command Prompt or Terminal window and navigate to the folder that contains the files you just extracted.
    3. Enter one of the following at the prompt.
      Windows:
      install.bat
      
      Linux:
      ./install.sh
      
    4. Read the license agreement that appears. Select I accept the terms of this license agreement, then click Next. Note: 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.
    5. Indicate where you want the file to be unpacked. It doesn't matter where because you will be manually placing the files in the appropriate directories later in these instructions.
    6. Click the Next button.
    7. The Installation Progress window appears. Progress bars indicate the status of the installation. When the installation progress is complete, click Quit to exit the Unpack Wizard.
  4. Navigate to the directory where you unpacked the files. Copy the pentaho.war and pentaho-style.war files to the appropriate directory. The directory you choose is determined by the web application server installed.
    • Tomcat: pentaho/server/biserver-ee/<your tomcat installation directory>/webapps
    • JBoss: pentaho/server/biserver-ee/<your jboss installation directory>/standalone/deployments
  5. Extract the pentaho-solutions.zip file to the pentaho/server/biserver-ee subdirectory. After you've extracted the zip file, the pentaho-solutions directory appears in the pentaho/server/biserver-ee directory.
  6. Extract the pentaho-data.zip file to the pentaho/server/biserver-ee subdirectory. After you've extracted the zip file, a data directory appears in the biserver-ee directory.
  7. Extract the license-installer.zip file to the pentaho/server directory. After you've extracted the zip file, the license-installer directory appears in the pentaho/server directory.
  8. If you unzipped the plugin files, copy the extracted plugin folders into the pentaho-solutions/system folder.
  9. Verify that the files have been placed in the following places by comparing the following directory structure with yours. Note: If your web application server is not in the pentaho/server/biserver-ee directory, the pentaho.war and pentaho-style.war files should appear where you've chosen to install your web application server.

Tomcat File Locations:

  • <your home directory>/.pentaho
  • pentaho/server/license-installer
  • pentaho/server/biserver-ee/<your tomcat installation directory>/webapps/pentaho.war
  • pentaho/server/biserver-ee/<your tomcat installation directory>/webapps/pentaho.war
  • pentaho/server/biserver-ee/<your tomcat installation directory>/webapps/pentaho-style.war
  • pentaho/server/biserver-ee/data
  • pentaho/server/biserver-ee/pentaho-solutions
  • pentaho/server/biserver-ee/pentaho-solutions/systems/default-content/samples-5.x.zip

JBoss File Locations:

  • <your home directory>/.pentaho
  • pentaho/server/license-installer
  • pentaho/server/biserver-ee/<your jboss installation directory>/standalone/deployments/pentaho.war
  • pentaho/server/biserver-ee/<your jboss installation directory>/standalone/deployments/pentaho-style.war
  • pentaho/server/biserver-ee/data
  • pentaho/server/biserver-ee/pentaho-solutions
  • pentaho/server/biserver-ee/pentaho-solutions/system/default-content/samples-5.x.zip

Set Environment Variables

Set the PENTAHO_JAVA_HOME variable to indicate the path to the Java JRE or JDK that Pentaho should use. Also, set the PENTAHO_INSTALLED_LICENSE_PATH variable so that when you start Pentaho, the licenses can install. If you do not set these variables, Pentaho will not start correctly. To set environment variables, you should be logged into an account that has administrator-level privileges. For Linux systems, you must be logged into the root user account.

Set Windows PENTAHO_JAVA_HOME and PENTAHO_INSTALLED_LICENSE_PATH Variables

  1. Open a Command Prompt.
  2. At the prompt, set the path of the PENTAHO_JAVA_HOME variable to the path of your Java 7 installation. Here is an example.
    SET PENTAHO_JAVA_HOME=C:\Program Files\Java\jre7
  3. At the prompt, set the path of the PENTAHO_INSTALLED_LICENSE_PATH variable to the .pentaho directory. Here is an example.
    SET PENTAHO_INSTALLED_LICENSE_PATH=C:\Users\pentaho\.pentaho\.installedLicenses.xml
    
  4. Optional: If you are using Instaview, set the path for the MONETDB_INSTALL_DIR variable to the path for the MonetDB location like this.
    MONETDB_INSTALL_DIR=C:\PE0A28~1\monetdb
  5. Verify the variables have been properly set.

Set Linux PENTAHO_JAVA_HOME and PENTAHO_INSTALLED_LICENSE_PATH Variables

  1. Open a terminal window and log in as root.
  2. Open the /etc/environment file with a text editor. Note:The vi and gedit text editors are available on most Linux machines. For example, to open the /etc/environment file with gedit, type this.
    gedit /etc/environment
    
  3. Indicate where you installed Java in your /etc/environment file by typing this. Note: Substitute /usr/lib/jvm/java-7-sun with the location of the JRE or JDK you installed on your system.
    export PENTAHO_JAVA_HOME=/usr/lib/jvm/java-7-sun
    
  4. Indicate the location of the .pentaho directory by typing this.
    export PENTAHO_INSTALLED_LICENSE_PATH=/home/pentaho/.pentaho/.installedLicenses.xml
    
  5. Save and close the file.
  6. Log out, then log back in for the change to take effect.
  7. Verify that the PENTAHO_JAVA_HOME variable is properly set by opening a Terminal window and typing this.
    env | grep PENTAHO_JAVA_HOME
    
  8. The path to the variable should appear. If it does not, try setting the environment variable again.
  9. Verify that the PENTAHO_INSTALLED_LICENSE_PATH variable is properly set by opening a Terminal window and typing this.
    env | grep PENTAHO_INSTALLED_LICENSE_PATH
    
  10. The path to the variable should appear. If it does not, try setting the environment variable again.

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 http://www.postgresql.org/docs/devel/static/kernel-resources.html and follow the instructions there on how to adjust the memory settings on your computer.