Skip to main content

Pentaho+ documentation is moving!

The new product documentation portal is here. Check it out now at


Hitachi Vantara Lumada and Pentaho Documentation

Installing the Pentaho Worker Nodes product

Parent article

When you are deploying a single-instance system, that instance is automatically configured as a master instance and runs all services for the system. The following instructions for installing a single-instance of Pentaho Worker Nodes includes the following steps.

  1. Configure the server or virtual machine
  2. Run Docker on each server or virtual machine
  3. Unpack the Pentaho Worker Nodes product package
  4. Running the setup script
  5. Start the application on the server or virtual machine
  6. Deploy the System
  7. Troubleshooting

Configure the server or virtual machine

Make the following changes on the server or virtual machine where you will install the Pentaho Worker Nodes product.


  1. Configure the mmap count. Add this line to the /etc/sysctl.conf file:

    vm.max_map_count = 262144
    NoteIf the line already exists, verify that the value is greater than or equal to ‘262144’.
  2. Configure the firewall rules to allow communication over all network ports that your system requires.

    NoteFor information on the ports that your system requires, see Networking.
  3. Restart the server or virtual machine.

Run Docker on each server or virtual machine

On the server or virtual machine that will host the Pentaho Worker Nodes instance, start Docker and keep it running. Use your usual tools for keeping services running in your environment.

For example, to run Docker using systemd, do the following.


  1. To check if Docker is running, run the following command.

    systemctl status docker
  2. If Docker is not running, start the Docker service.

    sudo systemctl start docker
  3. (Optional) Configure the Docker service to start automatically when you restart the server or virtual machine.

    sudo systemctl enable docker

Unpack the Pentaho Worker Nodes product package

On the server or virtual machine that will host the Pentaho Worker Nodes instance, perform the following steps.


  1. Retrieve the pentaho-workernodes-.tgz file and store it in a directory on the server or virtual machine.

  2. In the largest disk partition, create a directory called /pwn or a directory name of your choice.

    The command mkdir /<path>/pwn creates the /pwn directory in/opt
  3. Move the installation package to the /pwn directory:

    mv <path>/pentaho-workernodes-<prod-version-number>.tgz/<path>/pwn
  4. Navigate to the installation directory:

    cd /<path>/pwn
  5. Unpack the installation package:

    sudo tar -zxf pentaho-workernodes-<prod-version-number>.tgz
  6. Run the install script in the version-specific directory:

    sudo ./cluster/<platform-version>/bin/install

    For example: sudo ./cluster/1.5.0-142/bin/install


The install script can be run only once on each instance. You cannot rerun this script to try to repair or upgrade the Pentaho Worker Nodes instance.

Running the setup script

On each server or virtual machine that will host the Pentaho Worker Nodes instance, run the setup script with the applicable options. The options are based on an instance type of either secure or unsecure.
  • -i:

    The external network IP address for the instance that you are running the script on.

  • -I:

    The internal network IP address for the instance that you are running the script on.

  • -m:

    Comma-separated list of external network IP addresses of each master instance.

  • -M:

    Comma-separated list of internal network IP addresses of each master instance.

If you are enabling secure communication, you need all four of the above options. Use the following table to determine which options you need to use for your single-instance system:

Number of instances in the systemNetwork type usageOptions
Non-secure singleSingle network type for all servicesUse -i only
Non-secure multi-nodeExternal for all servicesUse -i only
Secure multi-nodeInternal for some services, external for othersUse both -i and -I, and both -m and -M. Both upper- and lower-case parameter values are required. Also, a master instance must be set for secure mode.
Example Commands
  • Non-secure single-instance system:
    sudo bin/setup -i
  • Secure multi-instance system:
    sudo bin/setup -i -I -m,, -M,,

The bin/setup command uses the lower-case parameters (-i and -m) for the external IP values and the upper-case parameters (-I and -M) for the internal IP values.

NoteIn the secure multi-instance system example, the setup command rotates the IP value for both the lower- and upper-case -i and I parameters per instance. However, the three masters are the same values for all instances.
NoteIf the terminal displays Docker errors when you run the setup script, verify that Docker is running. For information, see Run Docker on each server or virtual machine.

Start the application on the server or virtual machine

On each server or virtual machine that will host the Pentaho Worker Nodes instance, start the run application script using your usual methods for running scripts.

NoteVerify that the method you use can keep the run script running and can automatically restart it in the event of a server reboot or other availability event.

The following are some examples of how you can start the script.

Example 1: Run the script in the foreground

Run the following command:

sudo bin/run

When you run the script using this method, the script does not automatically complete. It remains running in the foreground.

Example 2: Run the script as a service using systemd

Perform the following steps to run the script as a service.


  1. If you have installed the Pentaho Worker Nodes product in a directory other than the default location, then edit the pentahoWorkerNodes.service file to point to that location.

    For example, in /<file-path>/bin/pentahoWorkerNodes.service, set the ExecStart parameter to the directory location as follows:
  2. Copy the pentahoWorkerNodes.service file to the appropriate location for your operating system, such as:

    cp /<file-path>/bin/pentahoWorkerNodes.service /etc/systemd/system
  3. Enable and start the search service as follows:

    sudo systemctl enable pentahoWorkerNodes.service

    sudo systemctl start pentahoWorkerNodes.service

    NoteWhen you activate the search service, systemctl may display the following message:

    The unit files have no [Install] section. They are not meant to be enabled using systemctl.
    Possible reasons for having this kind of units are: 
    1) A unit may be statically enabled by being symlinked from another unit's .wants/ or .requires/ directory. 
    2) A unit's purpose may be to act as a helper for some other unit which has a requirement dependency on it. 
    3) A unit may be started when needed via activation (socket, path, timer, D-Bus, udev, scripted systemctl call, ...)

    Depending on your OS, the search service may or may not have been enabled successfully. To avoid this situation, verify that you moved the pentahoWorkerNodes.service to the applicable location, which is typically /etc/systemd/system.

Deploy the System

After creating the instance, you need to use the Administration App service to deploy the system.


  1. Open a web browser and go to https://<instance-IP-address>:8000.

    NoteYou must enter https. You must also click through one or more security warnings.
  2. On the Welcome page, set a password for the initial admin user account, then click Set Admin Password. The Confirm Cluster Topology page displays all detected instances.

  3. If your system includes multiple instances, verify that all expected instances are listed. If they are not, click on the link in the Instance Discovery panel until they appear.

  4. (Optional) If you want to change networking settings for the services, perform the following steps:

    NoteIf you want to reconfigure networking for the Pentaho Worker Nodes services, you must do so now before deploying the system.
    1. Click the link in the Advanced Network Configuration section.

    2. (Optional) For each service, configure the ports that the service should use.

      NoteIf you reconfigure service ports, verify that each port value you assign is unique across all services, both System services and Pentaho Worker Nodes services.
    3. (Optional) For each service, specify which network the service should bind to, either Internal or External.

      NoteBy default, the Search-App and Admin-App services have the External option selected and all other services are set to Internal.
      If you are only using a single network, you can leave these settings as they are since all system instances are assigned both internal and external IP addresses. If you are only using a single network type, the internal and external IP addresses for each instance are identical.

      For more information, see Networking.

  5. Click the Deploy Single Instance or Deploy Cluster button. The system deployment starts. You can click on the View Deployment Details link to view the progress of the deployment.


You cannot change networking settings for System services at this point. However, if you configured the System services networking incorrectly, the Administration App may fail to appear. This failure may happen if the network.config file is not identical on all instances. For error information, view the /<installation-directory>/pwn/config/cluster.config file or the output information logged by the run script.

Next, you should check your network settings.

Check your networking settings

Perform the following steps.


  1. Stop the run script from running by using the method you are currently using to run the script.

  2. Run this command to stop all Docker containers on the instance:

    sudo systemctl stop pentahoWorkerNodes.service
  3. Delete the contents of the <install-path>/pwn/ directory from all instances.

  4. Begin the installation again from Unpack the Pentaho Worker Nodes product package

Next step: Set up mounted volumes

After installing Pentaho Worker Nodes, see Setting up mounted volumes on Pentaho Worker Nodes to continue the setup process.