Learn Pentaho - Installation & Getting to Know Spoon

#Introduction

Enough theory. In episode 3 you'll install PDI and open Spoon for the first time. You'll get to know every corner of its interface, understand the project and workspace structure, then create your first database connection that becomes the foundation of all transformations in the episodes that follow.

Follow the order slowly. The end goal isn't just having Spoon open, but feeling comfortable moving between the step palette, canvas, and connection panel without having to search around.

#Installing Pentaho Data Integration

PDI is distributed as an architecture-agnostic ZIP file, so installation is practically the same on Windows, Linux, and macOS: download, extract, make sure JDK is available, then run the appropriate script.

General installation steps:

Download Pentaho Data Integration Community Edition from the official Pentaho website — choose the latest version (for example PDI 9.x). As an alternative, use Pentaho Kettle from SourceForge for community releases.
Extract the ZIP file into your lab folder, for example /home/kalian/lab/pdi-ce.
Make sure JDK 8 or 11 is installed and JAVA_HOME points correctly (repeat episode 0 if needed).
Grant execute permissions to the scripts in that folder.
Run spoon.sh on Linux/macOS or Spoon.bat on Windows.

Example steps on Linux from the terminal:

Extract and prepare PDI on Linux

unzip pdi-ce-9.4.0.0-343.zip -d ~/lab
cd ~/lab/pdi-ce-9.4.0.0-343
chmod +x spoon.sh pan.sh kitchen.sh carte.sh
./spoon.sh

To run it again later, simply cd into the PDI folder then ./spoon.sh. On Windows, double-click Spoon.bat. If Spoon fails to open, the cause is almost always one of three things: a wrong JAVA_HOME, an unsupported JDK version, or an unconfigured HiDPI screen.

Info

On HiDPI screens, the Spoon interface can look very small. A quick fix: before running Spoon, set the PENTAHO_JAVA_HOME variable and add a scaling argument to JAVA_TOOL_OPTIONS such as -Dsun.java2d.uiScale=2 so the UI doesn't shrink.

#Verifying the Installation and Version

After Spoon opens successfully, make sure the installation is truly healthy by checking the version from the command line. All PDI runners accept the -version flag:

Check PDI version from the terminal

./pan.sh -version

The output shows the release and build number — important information when you search for solutions in the community or report bugs. Note your version: most forum answers discuss the behavior of a specific version, and even a patch number difference can change how a step behaves.

#Installation on macOS

On macOS the process is the same as Linux, with two small differences: you download the same ZIP file, extract it to /Applications or your home folder, then run ./spoon.sh from Terminal. If macOS blocks an unsigned application, open System Settings > Privacy & Security and allow the app. Make sure JAVA_HOME points to the chosen JDK via export JAVA_HOME=$(/usr/libexec/java_home -v 11) before running Spoon — this step is often the source of confusing failures on macOS.

#Getting to Know the Spoon Interface

When Spoon first opens, you'll be greeted by a Welcome panel with several main areas. Get to know these four parts early:

Palette (on the right): a list of steps grouped by category — Input, Output, Transform, Flow, Lookup, Scripting, and others. This is your "toy box".
Canvas (in the middle): the empty area where you place steps and connect them. This is where transformation/job designs are drawn.
Tree panel (on the left): shows the project structure, repository, database connections, and saved objects.
Status bar and tabs: each open transformation or job appears as a tab; execution logs appear in the bottom panel.

Before creating a transformation, create a new Transformation via the menu File > New > Transformation or click the icon in the toolbar. An empty canvas will appear — this is where you'll spend a lot of time in episode 4.

#Project and Workspace Structure

PDI follows the file-based pattern: every transformation is saved as a .ktr file and every job as a .kjb. On the left side, the View panel shows the following elements:

Database connections: all connections you define, saved and reusable across many files.
Transformation / Job: currently open files and the hierarchy of steps inside them.
Plugins: community steps you have installed.

Because files are XML-based, you're free to store projects in any folder and put them under version control. A good habit: one project per folder, with subfolders for transformations, jobs, and resources. The structure you created in episode 0 is correct and will be used from now on.

#Creating Your First Database Connection

Now for the part you've been waiting for. Open the View panel, right-click Database connections, select New, then fill in the connection form. Choose the database type, for example PostgreSQL, give the connection any name, set host to localhost, port 5432, database lab, and user and password matching your lab container from episode 0.

After saving, click the Test button to make sure the connection works. If a success message appears, the connection is ready for the Table input, Table output, and Database lookup steps in the following episodes.

You can also test the connection from the command line using Spoon to produce detailed logs. If you're unsure about connection parameters, click the Browse button next to the field to see a help form showing the JDBC URL that will be used.

Success

The golden habit: name connections that describe their environment, for example LAB_PG for lab PostgreSQL and PROD_PG for production. This prevents you from connecting to the wrong database when running transformations — a very common and painful mistake.

#Exploring the Log Panel and Step Metrics

When you later run transformations, the log panel at the bottom will be your second pair of eyes. A few things to recognize early:

Log tree: each step has its own log tab with detailed messages such as the number of rows read and written.
Step Metrics: a table showing each step's performance — lines input, lines output, lines read, lines written, errors, and active.
Execution history: an execution trail that helps you compare previous runs.

From now on, get into the habit of reading the log panel every time you run something. Episode 7 will cover debugging and error handling in depth, but training your eyes to read logs early will pay off.

#Saving and Reopening Projects

Whenever you create a new file, save it right away with a descriptive name. In this episode, save your empty transformation as first_steps.ktr in the transformations folder. A good file name describes the content and sequence, for example etl_order_staging.ktr rather than trans_kirim.ktr.

To reopen, simply File > Open or drag the .ktr file onto the canvas. .kjb files open the same way. The habit of saving and naming files correctly will help a lot in episode 9 when you start applying version control with Git.

#Conclusion

In episode 3 you installed PDI, opened Spoon, got to know the four main areas of its interface, understood the file-based project structure, and successfully created your first tested database connection.

The key takeaways:

Installing PDI is a matter of extract, JDK, and running a script — there's no complicated wizard.
Palette, canvas, tree panel, and log are the four areas you'll always use in Spoon.
Database connections are saved once and can be reused across many .ktr files.
Consistent naming for files and connections saves you in large projects.

In episode 4, we'll get straight into practice: building a basic transformation — using input steps like Table input and Text file input, transformations like Filter rows and Join, understanding the row stream and field metadata, then running it and checking the data preview.