Install Pentaho Server

Installation of Pentaho Server components ..

Pentaho Server

This section guides you through installing and starting the Pentaho Server on Ubuntu.

You will:

Create installation directories
Prepare the Pentaho Repository databases
Configure JDBC/JNDI connections
Start the Pentaho Server (and optionally set up systemd)
Configure the License Manager

Tested baseline: Ubuntu 24.04 LTS with Java 21 (OpenJDK) and PostgreSQL 17.

Make sure you have completed Prepare Environment first.

For compatibility details, see Components Reference.

Prerequisites

Ubuntu 24.04 LTS server
Java 21 installed and PENTAHO_JAVA_HOME set
PostgreSQL 17 installed and running
A non‑root pentaho user with sudo
unzip package installed
Archive ZIPs and JDBC drivers downloaded

Pentaho Server Directories

The Pentaho Server is a web application running in a Apache Tomcat servlet container.

Create base directories under /opt/pentaho.

cd
sudo mkdir -p /opt/pentaho/{server,software}

/opt/pentaho
├── server      # Unpacked server runtime (tomcat, pentaho-solutions, scripts)
└── software    # Installers, ZIPs, drivers (staging area)

Create sub-directories in /opt/pentaho/software.

cd /opt/pentaho/software
sudo mkdir -p {db-drivers,docker,ee-client,ee-plugins,ops-mart,sdk,server,shims}

db-drivers   - JDBC drivers
docker       - Pentaho on-prem config & dockerfiles
ee-client    - Pentaho EE client plugins
ee-plugins   - Pentaho EE server plugins
ops-mart     - Operations Mart scripts
sdk          - Pentaho SDK kit
server       - Pentaho server
shims        - Hadoop shims collections

Unpack Pentaho Server Package (ZIP)

Use unzip to extract the server ZIP into the runtime directory. This avoids requiring the full JDK (the JRE does not include the jar tool).

pentaho-server-ee-11.0.0.0-2xx.zip - Pentaho Server (Archive - incl Tomcat 10)

Ensure unzip is available and copy the server ZIPs into staging.

cd
sudo apt update -y && sudo apt install -y unzip
sudo cp ~/Downloads/'Archive Build (Suggested Installation Method)'/* /opt/pentaho/software/server

Extract the Pentaho Server ZIP into $PENTAHO_BASE/server.

cd
cd "$PENTAHO_BASE/server"

# Replace <version> with the exact file name you downloaded
sudo unzip /opt/pentaho/software/server/pentaho-server-ee-11.0.0.0-2xx.zip

Make all .sh files executable.

cd
cd "$PENTAHO_BASE/server"
sudo find . -iname "*.sh" -exec chmod +x {} \;

Set ownership and sensible permissions to run 'pentaho' as a non-root user.

cd
sudo chown -R pentaho:pentaho /opt/pentaho
sudo find /opt/pentaho -type d -exec chmod 755 {} \;
sudo find /opt/pentaho -type f -exec chmod 644 {} \;
sudo find /opt/pentaho -name "*.sh" -exec chmod 755 {} \;

755 means you can do anything with the file or directory, and other users can read and execute it but not alter it. Suitable for programs and directories you want to make publicly available.

644 means you can read and write the file or directory and other users can only read it.

Verify the server directory structure.

/opt/pentaho/

  server/
    pentaho-server/
      pentaho-solutions/
        system/

Server plugins are installed into the pentaho-solutions/system folder.

Pentaho Repository components

The Pentaho Repository (on PostgreSQL by default) consists of:

Jackrabbit: solution repository, security and content metadata
Quartz: scheduler data
Hibernate: audit logging
Pentaho Operations Mart: usage and performance reporting

Review default passwords in SQL scripts

Inspect the PostgreSQL scripts shipped with the server.

cd
cd "$PENTAHO_SERVER/data/postgresql"
ls -1

You should see files similar to:

alter_script_postgresql_BISERVER-13674.sql
create_jcr_postgresql.sql
create_quartz_postgresql.sql
create_repository_postgresql.sql
migrate_old_quartz_data_postgresql.sql
pentaho_logging_postgresql.sql
pentaho_mart_drop_postgresql.sql
pentaho_mart_postgresql.sql
pentaho_mart_upgrade_audit_postgresql.sql
pentaho_mart_upgrade_postgresql.sql

Open a script to review default users/passwords (change for production).

sed -n '1,120p' create_jcr_postgresql.sql

Production guidance: use unique, strong passwords, rotate them regularly, store them in a secure vault, and never commit secrets to source control.

Do not keep workshop password defaults in production.

Run SQL scripts to create Repository databases

Confirm PostgreSQL is running and locate the scripts.

sudo systemctl status postgresql --no-pager
cd
cd "$PENTAHO_SERVER/data/postgresql"
ls -l

Connect as a pentaho superuser.

Password: SecurePassword123

sudo -u pentaho psql -d postgres

Execute the commands step-by-step - not as a single script block. Provide passwords if prompted - see below.

\i create_jcr_postgresql.sql
\i create_quartz_postgresql.sql
\q quit after Quartz and log back in ..
ensure your in the "$PENTAHO_SERVER/data/postgresql" directory
sudo -u pentaho psql -d postgres
\i create_repository_postgresql.sql
\i pentaho_mart_postgresql.sql
\q quit after hibernate and log back in ..
ensure your in the "$PENTAHO_SERVER/data/postgresql" directory
sudo -u pentaho psql -d postgres
\i pentaho_logging_postgresql.sql
\q

User

Password

postgres

SecurePassword123

pentaho

SecurePassword123

jcr_user

password

pentaho_user

password

hibuser

password

Quick validation (CLI) - list created databases and connect - hit q to scroll through list.

\l+ jackrabbit
\l+ quartz
\l+ hibuser
\l+ opsmart
\c jackrabbit
\dt
\c quartz
\dt

Tables for Hibernate and Jackrabbit may be created later by the Pentaho Server on first start. Seeing empty schemas at this stage can be expected.

Optional: verify in pgAdmin (GUI).

Configure Pentaho to use PostgreSQL

PostgreSQL is the default. If you kept the default passwords and port (5432), only verify the settings below; otherwise, adjust host/port/user/password to match your environment.

Quartz - set PostgreSQL delegate and JNDI data source.

Open the Quartz configuration.

cd "$PENTAHO_SERVER/pentaho-solutions/system/scheduler-plugin/quartz"
sudo nano -c quartz.properties

Check these values (line numbers may differ):

quartz.properties — required entries

org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
org.quartz.dataSource.myDS.jndiURL=Quartz

Hibernate — point to the PostgreSQL configuration file.

Open Hibernate settings.

cd "$PENTAHO_SERVER/pentaho-solutions/system/hibernate"
sudo nano -c hibernate-settings.xml

Confirm the config file reference:

hibernate-settings.xml

<config-file>system/hibernate/postgresql.hibernate.cfg.xml</config-file>

Optionally review postgresql.hibernate.cfg.xml for datasource name and dialect.

sudo nano -c postgresql.hibernate.cfg.xml

Ensure:

postgresql.hibernate.cfg.xml — key properties

<property name="connection.driver_class">org.postgresql.Driver</property>
<property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property>
<property name="hibernate.connection.datasource">java:comp/env/jdbc/Hibernate</property>

Jackrabbit — verify PostgreSQL storage in repository.xml.

Open Jackrabbit configuration.

cd "$PENTAHO_SERVER/pentaho-solutions/system/jackrabbit"
sudo nano -c repository.xml

Check that PostgreSQL sections are active (others commented out), for example:

Filesystem schema: postgresql
Datastore databaseType="postgresql"
PersistenceManager schema: postgresql
Database Journal: postgresql

Cross‑check JNDI names and ports across Quartz, Hibernate, Jackrabbit, and Tomcat context.xml to ensure consistency (same host, port 5432 unless changed, and matching JNDI resource names).

Expected JNDI names:

Quartz: Quartz
Hibernate: java:comp/env/jdbc/Hibernate
Jackrabbit: as referenced in repository.xml

Tomcat

After configuring the Repository, configure the web application server (Tomcat 10) to connect to the Repository using JDBC/JNDI.

JDBC Drivers

To connect to databases (including the Repository), install the appropriate JDBC drivers. Due to licensing restrictions, some drivers must be downloaded manually.

JDBC drivers reference | Pentahodocs.pentaho.com

https://jdbc.postgresql.org/download/postgresql-42.7.8.jarjdbc.postgresql.org

Verify the PostgreSQL JDBC driver is present in Tomcat lib (required for the Repository):

ls -1 "$TOMCAT_HOME/lib" | grep -i postgresql || echo "PostgreSQL driver not found"

If not found, download the PostgreSQL JDBC driver (e.g., postgresql-42.7.8.jar) and distribute it using the helper script:

sudo cp ~/Downloads/'Database Drivers'/postgresql-*.jar /opt/pentaho/server/jdbc-distribution
cd /opt/pentaho/server/jdbc-distribution
sudo ./distribute-files.sh "$TOMCAT_HOME/lib"

Copy any additional JDBC drivers to the staging folder and distribute.

sudo cp ~/Downloads/'Database Drivers'/* /opt/pentaho/software/db-drivers
cd /opt/pentaho/software/db-drivers
sudo cp mysql-connector-j-9.0.0.jar /opt/pentaho/server/jdbc-distribution

Distribute the drivers to Tomcat.

cd /opt/pentaho/server/jdbc-distribution
sudo ./distribute-files.sh "$TOMCAT_HOME/lib"

Verify the JARs are present in Tomcat lib.

ls -1 "$TOMCAT_HOME/lib" | grep -Ei 'mysql|postgresql' || echo "Not found"

You must restart the Pentaho Server (and client tools, if running) to load new JDBC drivers. A full system reboot is not required.

context.xml

Database connection information for JNDI resources used by Pentaho is stored in context.xml.

Open the file and review JNDI resources and credentials.

cd "$TOMCAT_HOME/webapps/pentaho/META-INF"
sudo nano -c context.xml

In production, verify username, password, driver class, host/IP, and port match your environment. Ensure JNDI names align with Quartz, Hibernate, and Jackrabbit configurations.

Start Pentaho Server

Run the server as the pentaho user to avoid permission issues.

Start the server.

cd
cd "$PENTAHO_SERVER"
./start-pentaho.sh

Tail the Tomcat log (robust pattern).

tail -f "$TOMCAT_HOME/logs/catalina."*.log

Expected messages include:

... Starting ProtocolHandler ["http-nio-8080"]
... Server startup in [xxxxx] milliseconds

Pentaho User Console (PUC)

The Pentaho User Console (PUC) is the web UI for creating and viewing content.

Default credentials (change immediately after first login):

Username: admin
Password: password

You also have the option to switch to the new login screen.

http://localhost:8080/pentaho/content/login/web/index.htmllocalhost

If you have already entered your licensing details, then you will be redirected to the new User Console.

Quick validations

Check HTTP is responding:

curl -I http://localhost:8080/pentaho/ | head -n 1

Optional (remote access): open firewall and test from a client machine (adjust to your network policy):

sudo ufw allow 8080/tcp || true

Validate Repository after first run (click to expand)

-- Quartz example
\c quartz
SELECT COUNT(*) FROM qrtz_scheduler_state;

-- Hibernate example (expect many tables after first start)
\c hibuser
\dt

Systemd (optional)

Create a systemd service to manage Pentaho at boot and on failure.

Save the unit file as /etc/systemd/system/pentaho-server.service.

/etc/systemd/system/pentaho-server.service

[Unit]
Description=Pentaho Server
After=network-online.target
Wants=network-online.target

[Service]
Type=forking
User=pentaho
Group=pentaho
EnvironmentFile=-/etc/environment
# Optional fallback if not using PENTAHO_JAVA_HOME in /etc/environment
# Environment="JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64"
WorkingDirectory=/opt/pentaho/server/pentaho-server
ExecStart=/opt/pentaho/server/pentaho-server/start-pentaho.sh
ExecStop=/opt/pentaho/server/pentaho-server/stop-pentaho.sh
TimeoutSec=500
Restart=on-failure
RestartSec=5
SuccessExitStatus=5 6
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

Reload and start.

sudo systemctl daemon-reload
sudo systemctl start pentaho-server
sudo systemctl enable pentaho-server

Manage the service:

sudo systemctl status pentaho-server
sudo systemctl restart pentaho-server
sudo systemctl stop pentaho-server

Troubleshooting (click to expand)

HTTP 404 on /pentaho after startup: confirm "$TOMCAT_HOME/webapps/pentaho" exists, check catalina.*.log for deployment errors, and verify file permissions under $PENTAHO_SERVER.
Port 8080 already in use: change Tomcat port in server.xml or stop the conflicting service.
JDBC driver not found: verify the driver JARs (e.g., postgresql-*.jar, mysql-*.jar) exist in "$TOMCAT_HOME/lib".
Authentication to PostgreSQL fails: prefer scram-sha-256; review pg_hba.conf, restart PostgreSQL, and test psql -h 127.0.0.1 with the target user.
Jackrabbit schema issues: re-check repository.xml sections are set to postgresql.
License activation errors: check Tomcat logs in tomcat/logs/ for license/elm messages.

Licensing Manager

Pentaho Pro Suite 11.x uses a License Manager (cloud or local) to manage PDI & BA entitlements and verify EE plugins.

Trial license

A 30-day trial license is included if you have downloaded from: Pentaho 30-day Trial

If you have dowwnloaded the GA binaries from: Pentaho Customer Portal, then you will require an Activation ID or your LIcensing URL.

If you have installed in an air-gapped envirnoment, you will need to request an offline license.

Launch Pentaho Server > Administration > Licenses to open the Add License dialog.
Click the + sign.

Enter Activation code or your licensing URL:

Enterprise licenses

If upgrading from 9.x or earlier, install the new product version before activating licenses. Do not start the server before upgrading the licenses.

Set license path environment variable

Create a PENTAHO_LICENSE_INFORMATION_PATH environment variable so the Pentaho Server consistently finds your license file.

Ensure the target directory exists and is secured.

sudo -u pentaho mkdir -p /home/pentaho/.pentaho
sudo chown -R pentaho:pentaho /home/pentaho/.pentaho
chmod 700 /home/pentaho/.pentaho

Edit /etc/environment and add the line below (no export).

sudo nano /etc/environment

Append (or update) the following:

PENTAHO_LICENSE_INFORMATION_PATH=/home/pentaho/.pentaho/.elmLicInfo.plt

Log out/log in or reload the environment and verify.

source /etc/environment
env | grep PENTAHO_LICENSE_INFORMATION_PATH

The PENTAHO_LICENSE_INFORMATION_PATH variable is now set.

PreviousPrepare Environment NextServer Plugins

Last updated 4 days ago

Was this helpful?

Good afternoon

hashtagPentaho Server

hashtagPentaho Server Directories

hashtagPentaho Repository components

hashtagTomcat

hashtagJDBC Drivers

hashtagcontext.xml

hashtagStart Pentaho Server

hashtagLicensing Manager

hashtagTrial license

Pentaho Server

Pentaho Server Directories

Pentaho Repository components

Tomcat

JDBC Drivers

context.xml

Start Pentaho Server

Licensing Manager

Trial license