Prepare Environment

Preflight tasks ..

Prepare Environment

Prepare your Ubuntu server for an Archive installation of the Pentaho Server.

This process will:

• Create a pentaho installation user (with sudo)

• Set Pentaho paths - $PENTAHO_BASE

• Install Java 21 (OpenJDK)

• Set PENTAHO_JAVA_HOME

• Install PostgreSQL 17 (15 supported for Pentaho 11)

• Create repository database user - pentaho for setup

• Install pgAdmin 4 (desktop)

Supported Linux baseline for Pentaho 11.x: Ubuntu 24.04 LTS.

For versions and compatibility, see Components Reference.

1

Prerequisites

1. Ensure unzip is installed.

unzip --version

1. Set the Pentaho path variables.

Use these variables to simplify commands and avoid path mistakes. Consider adding them to your shell profile for convenience.

• Edit the /etc/environment file.

cd
cd /etc/
sudo nano environment

• Add the following paths.

# Pentaho paths
PENTAHO_BASE=/opt/pentaho
PENTAHO_SERVER=/opt/pentaho/server/pentaho-server
TOMCAT_HOME=/opt/pentaho/server/pentaho-server/tomcat

If you add these to ~/.bashrc or /etc/environment, re-open your shell or source the file to apply.

Pentaho paths

2

Create a Pentaho installation user

For production, use a dedicated installation account with only the required privileges and avoid sharing credentials.

1. Update packages (run once):

sudo apt update -y && sudo apt upgrade -y

1. Add the user and set a password:

sudo adduser pentaho

1. Grant sudo privileges:

sudo usermod -aG sudo pentaho

1. Validate access:

su - pentaho
groups
sudo -v

3

Install Java 21 (OpenJDK)

Pentaho 11.x is certified with Java 21.

What's the difference bewteen Oracle JDK & OpenJDK?

Oracle JDK and OpenJDK are both implementations of the Java Platform, but they have some important differences:

Licensing and Cost:

• OpenJDK is completely free and open source under the GPL license. You can use it for any purpose without restrictions.

• Oracle JDK changed its licensing model in 2019. It's now free for development and personal use, but requires a paid subscription for commercial production use (Oracle Java SE Subscription).

Source and Development:

• OpenJDK is the reference implementation of Java and serves as the base for most JDK distributions. Oracle actually contributes significantly to OpenJDK development.

• Oracle JDK is built from the OpenJDK source code but includes some additional proprietary components and commercial features.

Performance and Features:

• In modern versions (Java 11+), the performance differences are negligible. Oracle has contributed most of its performance improvements back to OpenJDK.

• Oracle JDK historically included some additional tools and features (like Java Flight Recorder and Java Mission Control), but many of these have been open-sourced and are now available in OpenJDK.

Support and Updates:

• OpenJDK receives community support and updates for about 6 months per release (except for LTS versions maintained by various vendors).

• Oracle JDK offers Long Term Support (LTS) with commercial subscriptions, providing updates and security patches for extended periods.

Other Distributions: Many vendors offer their own builds of OpenJDK with long-term support, including Amazon Corretto, Azul Zulu, Eclipse Temurin (formerly AdoptOpenJDK), and Red Hat OpenJDK.

For most developers and organizations, OpenJDK or vendor-supported OpenJDK distributions are the go-to choice unless you specifically need Oracle's commercial support.

1. Install Java 21:

sudo apt install -y openjdk-21-jre-headless

1. Verify Java:

java -version
which java
readlink -f $(which java)

OpenJDK versions

Java 21

If multiple Java versions are installed, select the default:

sudo update-alternatives --config java

4

Set PENTAHO_JAVA_HOME

Set PENTAHO_JAVA_HOME globally so the Pentaho Server consistently uses Java 21.

1. Edit /etc/environment:

sudo nano /etc/environment

1. Add (or update) the following line:

# set PENTAHO_JAVA_HOME
PENTAHO_JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

Set PENTAHO_JAVA_HOME

1. Save and reload the environment (or log out/in):

source /etc/environment

1. Verify:

echo $PENTAHO_JAVA_HOME

---

Alternative: set for a single user only in ~/.bashrc.

1. Edit:

nano ~/.bashrc

1. Append and apply:

export PENTAHO_JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
. ~/.bashrc

5

Install PostgreSQL 17

Ubuntu 24.04’s default repository provides a newer PostgreSQL 16. To install 17, add the official PostgreSQL (PGDG) repository.

If a different PostgreSQL is already present, purge it first to avoid port and package conflicts (see the optional "Clean previous installs" tab).

Prerequisites Ubuntu 24.04 Root privileges or sudo access use sudo su to get into root instead of pentaho (default user)

Install PostgreSQL 17

1. Before installing PostgreSQL, ensure your system is up to date.

sudo apt update && sudo apt upgrade -y

1. Install prerequisite packages.

sudo apt install -y wget ca-certificates

1. Import PostgreSQL GPG Key.

wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

1. Add PostgreSQL Repository

sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

1. Update Package List.

sudo apt update

1. Install PostgreSQL 17 server and client packages.

sudo apt update -y && sudo apt upgrade -y
sudo apt install -y postgresql-17 postgresql-contrib-17

What gets installed:

• postgresql-17: Main database server

• postgresql-contrib-17: Additional utilities and extensions

1. Check service and version:

sudo systemctl status postgresql --no-pager
psql --version

PostgreSQL 17.7

1. Optional tidy up:

sudo apt autoremove -y

Optional: Install PostgreSQL 16

Optional: Clean previous installs

Validation:

sudo systemctl is-enabled postgresql
sudo ss -ltnp | grep 5432 || true
sudo -u postgres psql -c "SELECT version();"

6

Create database user - pentaho

During install, PostgreSQL creates a local superuser postgres. Set its password and (optionally) creates a dedicated pentaho role.

For production, avoid a permanent superuser for application use. Use least-privilege roles and grant only what is needed. The workshop path below elevates privileges to simplify setup.

1. Switch to the postgres system user.

sudo -i -u postgres

1. Enter the PostgreSQL interactive terminal.

psql

1. You should see the PostgreSQL prompt:

postgres=#

1. View current databases.

\l

This lists all databases. You should see three default databases: postgres, template0, and template1.

1. Exit.

q

1. Check PostgreSQL Version from SQL.

SELECT version();

1. Exit PostgreSQL Prompt.

\q

1. And Exit psql.

exit

---

Create pentaho user

1. Set postgres password:

sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'SecurePassword123';"

1. Create a pentaho user and grant SUPERUSER privileges:

sudo -u postgres psql -c "CREATE USER pentaho WITH PASSWORD 'SecurePassword123';"
sudo -u postgres psql -c "ALTER USER pentaho WITH SUPERUSER;" # Demo only

• sudo -u postgres - Run the command as the Linux system user postgres (who has local access to PostgreSQL without a password)

• psql -c - Execute a single SQL command and exit

• CREATE USER pentaho - Creates a new PostgreSQL role/user named pentaho

• WITH PASSWORD 'SecurePassword123' - Sets the password for this user

---

• ALTER USER pentaho - Modifies the existing pentaho user

• WITH SUPERUSER - Grants full superuser privileges (can do anything: create databases, create users, bypass all permissions, etc.)

• # Demo only - Warning comment indicating this is dangerous for production

1. Test connection as pentaho:

sudo -u pentaho psql -d postgres -c "\conninfo"

7

Optional: Allow remote connections

For reference only as connecting to Postgresql via localhost

By default, PostgreSQL accepts only local connections. For localhost setups, you do not need this step.

1. Back up configs and edit postgresql.conf (PostgreSQL 17):

sudo cp /etc/postgresql/17/main/postgresql.conf{,.bak}
sudo nano /etc/postgresql/17/main/postgresql.conf

1. Set: listen_addresses = '*' (a specific interface/IP in production)

Set listener

1. Save:

Ctrl + o
Enter
Ctrl + x

8

Configure pg_hba.conf

The pg_hba.conf file (PostgreSQL Host-Based Authentication configuration) controls who can connect to your PostgreSQL database and how they authenticate. You configure it during installation to define security rules for database access.

In production you would modify the settings to only allow the required users access to the databases on Server IPs.

1. Configure PostgreSQL to use md5 password authentication pg_hba.conf .

sudo cp /etc/postgresql/17/main/pg_hba.conf{,.bak}
sudo nano /etc/postgresql/17/main/pg_hba.conf

1. Manually edit the file:

Or

1. Run the following script.

# Use the exact path
PG_HBA_PATH=/etc/postgresql/17/main/pg_hba.conf

# Verify the file exists
ls -la "$PG_HBA_PATH"

# If that works, then run:
sudo cp "$PG_HBA_PATH" "${PG_HBA_PATH}.backup"
sudo sed -i 's/^local[[:space:]]\+all[[:space:]]\+postgres[[:space:]]\+peer$/local   all             postgres                                scram-sha-256/' "$PG_HBA_PATH"
sudo sed -i 's/^local[[:space:]]\+all[[:space:]]\+all[[:space:]]\+peer$/local   all             all                                     scram-sha-256/' "$PG_HBA_PATH"
sudo sed -i '0,/^host[[:space:]]\+all[[:space:]]\+all[[:space:]]\+127\.0\.0\.1\/32[[:space:]]\+scram-sha-256$/s//host    all             all             0.0.0.0\/0               md5/' "$PG_HBA_PATH"

# Verify
sudo cat "$PG_HBA_PATH" | grep -E "^(local|host)[[:space:]]+(all|replication)"

SED: pg_hba.conf

Prefer scram-sha-256 over md5 in pg_hba.conf for stronger password hashing on modern PostgreSQL versions.

Ensure your JDBC driver supports SCRAM (e.g., recent PostgreSQL drivers). If compatibility issues arise, use md5 as a fallback.

1. Restart the PostgreSQL service.

cd
systemctl restart postgresql
# Password: password

1. Allow firewall (if enabled) and restart:

sudo ufw allow 5432/tcp || true
sudo systemctl restart postgresql
sudo ss -ltnp | grep 5432

9

Install pgAdmin 4 (desktop)

Install the pgAdmin 4 desktop client using the official repository.

1. Add repo and key:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsS https://www.pgadmin.org/static/packages_pgadmin_org.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/packages-pgadmin-org.gpg > /dev/null
source /etc/os-release
echo "deb [signed-by=/etc/apt/keyrings/packages-pgadmin-org.gpg] https://ftp.postgresql.org/pub/pgadmin/pgadmin4/apt/${UBUNTU_CODENAME} pgadmin4 main" | sudo tee /etc/apt/sources.list.d/pgadmin4.list

1. Install pgAdmin 4 (desktop):

sudo apt update -y && sudo apt upgrade -y
sudo apt install -y pgadmin4-desktop

1. Optional: verify repo entry

cat /etc/apt/sources.list.d/pgadmin4.list

1. Add a server connection in pgAdmin:

• Right‑click Servers → Register → Server

• Name: Pentaho

• Connection: host, port 5432, user pentaho, password SecurePassword123 (do not save in production)

Create server group

Server group

Connection details

Do not save passwords in production. Prefer OS‑level keyrings or secure vaults.

pgAdmin 4 UI

10

Validate the environment

1. Quick checks to confirm everything is ready for the next step.

# Java
java -version
[ "$PENTAHO_JAVA_HOME" = "/usr/lib/jvm/java-21-openjdk-amd64" ] && echo OK || echo "Check PENTAHO_JAVA_HOME"

# PostgreSQL
sudo -u postgres psql -c "SELECT version();"
sudo systemctl status postgresql --no-pager | sed -n '1,5p'

Validate PostgreSQL 17 service ..

---