Install Pentaho Worker Nodes on a Single Instance of HCI
Now that you have packaged the Pentaho Worker Nodes product, you are ready to install the PentahoWorkerNodes package following these excerpted instructions from the HCI Install Guide. It is recommended that you download the complete HCI Install Guide located in the distribution. Use it for reference and for building multi-instance systems on your own. Please make sure you follow all installation and configuration instructions specified in this section for the server executing the Pentaho Worker Nodes product. In Unpack the Pentaho Worker Nodes Package, make sure you use the product you created with the scripts previously executed in the previous steps.
Prior to installation, make sure you import the trial license file
pentaho-hci-trial-license while setting up the product. See Download the Required Licenses for more information.
Since you are deploying a single-instance system, that instance will automatically be configured as a master instance and run all services for the system.
The following instructions for installing a single-instance of Pentaho Worker Nodes product with HCI includes the following steps:
- Configure the Server or Virtual Machine
- Run Docker on Each Server or Virtual Machine
- Unpack the Pentaho Worker Nodes Product Package
- Optional: Set Up Networking for System Services
- Run the Setup Script
- Start the Application on the Server or Virtual Machine
- Deploy the System
- Troubleshooting: Check Your Networking Settings
Configure the Server or Virtual Machine
Make the following changes on the server or virtual machine that is to be a Pentaho Worker Nodes product on an HCI instance.
- Configure the mmap count. Add this line to the
vm.max_map_count = 262144
If the line already exists, ensure that the value is greater than or equal to ‘262144’.
- Configure the firewall rules to allow communication over all network ports that your system requires.
For information on the ports that your system requires, see Networking.
- Restart the server or virtual machine.
Run Docker on Each Server or Virtual Machine
On the server or virtual machine that is to be an HCI instance, you need to start Docker and keep it running. You can use whatever tools you typically use for keeping services running in your environment.
For example, to run Docker using
systemd, do the following.
- To check if Docker is running, run the following command.
systemctl status docker
- If Docker is not running, start the Docker service.
sudo systemctl start docker
- Optionally, 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 is to be the Pentaho Worker Nodes product on an HCI instance, perform the following steps.
- Retrieve the
PentahoWorkerNodes-1.0.0.tar.gzfile and store it in a directory on the server or virtual machine.
- In the largest disk partition, create a directory called
/hci directory in
/opt. Your system includes an
HCI.service script that you can use to run the application. By default, this script expects the system to be installed in
- Move the installation package to the
mv <path>/ PentahoWorkerNodes-1.0.0.tar.gz /<path>/hci
- Navigate to the installation directory:
- Unpack the installation package:
sudo tar -zxf PentahoWorkerNodes-1.0.0.tar.gz
- Run the install script in the version-specific directory:
- Do not change directories after running the install script. The following steps are performed in your current directory, not under the version-specific directory.
- 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 Product on HCI instance.
Optional: Set Up Networking for System Services
If you want to reconfigure networking for the System services, you must complete this step before Run the Setup Script.
You cannot change networking for System services after running the setup script or after starting
You can change these networking settings for each service in your product:
- The ports that the service uses.
- The network to listen on for incoming traffic, either internal or external.
You configure networking for System services in this step, before running the product startup scripts. You configure networking for HCI services later during Deploy the System step. For more information, refer to the HCI Install Guide included with your installation.
To configure networking for the System services:
- On the server or virtual machine that will be the Pentaho Worker Nodes product on an HCI instance, open the
/<hci-installation-directory>/config/network.configfile in a text editor.
The file contains two types of lines for each service:
- Network type assignments:
- Port number assignments:
- Optionally, specify new port values for the services you want to configure.
- If you reconfigure service ports, make sure that each port value you assign is unique across all services, both System services and HCI services.
- By default, all System services are set to internal.
- If you are only using a single network, you can leave these settings as they are. All system instances are assigned both internal and external IP addresses in HCI; if you are only using a single network type, the internal and external IP addresses for each instance are identical.
For information on the ports that each service uses, see Ports.
- Optionally, on the lines containing an interface, specify the network that the service should use. Valid values are ‘internal’ and ‘external’.
- Ensure that the
network.configfile is identical on all HCI instances.
Run the Setup Script
On each server or virtual machine that will be the Pentaho Worker Nodes Product on an HCI 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.
Note that you will need all four of the above options if you are enabling secure communication. Use the following table to determine which options you need to use for your single-instance system:
|Number of instances in the system||Network type usage||Options|
|Unsecure Single||Single network type for all services||
Use -i only
|Secure Single||Internal for some services, external for others||Use 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.|
- For an unsecure single-instance system:
sudo bin/setup -i 192.0.2.4
- For a secure single-instance system:
sudo bin/setup -i 192.0.2.4 -I 192.0.2.4 -m 192.0.2.4 -M 192.0.2.4
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.
If the terminal displays Docker errors when you run the setup script, ensure 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 is to be the Pentaho Worker Nodes Product on an HCI instance, start the run application script using whatever methods you usually use to run scripts.
Ensure that the method you use can keep the run script running and can automatically restart it in case of a server reboot or other availability event.
Here are some examples of how you can start the script:
Example 1: Run the script in the foreground
Run the following command:
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.
- If you have installed the Pentaho Worker Nodes product in a directory other than the default location, then edit the
pentahoWorkerNodes.servicefile to point to that location. For example, in
/<file-path>/bin/pentahoWorkerNodes.service, set the ExecStart parameter to the directory location as follows:
- Copy the
pentahoWorkerNodes.servicefile to the appropriate location for your operating system, such as:
cp /<file-path>/bin/pentahoWorkerNodes.service /etc/systemd/system
- Enable and start the search service as shown below:
sudo systemctl enable pentahoWorkerNodes.service
sudo systemctl start pentahoWorkerNodes.service
When you enable 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 successfully been enabled.
To avoid this situation, make sure that you moved the
pentahoWorkerNodes.service to the appropriate location, which is typically
Deploy the System
After creating your instance, you need to use the Administration App to deploy the system.
- Open a web browser and go to
You must enter ‘
https’. You must also click through one or more security warnings.
- 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.
- If your system includes multiple instances, ensure that all expected instances are listed. If they are not, click on the link in the Instance Discovery panel until they appear.
- Optionally, if you want to change networking settings for the HCI services, perform the following steps:
If you want to reconfigure networking for the HCI services, you must do so now before deploying the system.
- Click on the link in the Advanced Network Configuration section.
- Optionally, for each service, configure the ports that the service should use.
If you reconfigure service ports, make sure that each port value you assign is unique across all services, both System services and HCI services.
- Optionally, for each service, specify which network the service should bind to, either Internal or External.
By 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 in HCI. 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.
- Click on 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.
Troubleshooting: Check Your Networking Settings
You cannot change networking settings for System services at this point.
Alternatively, if you configured the System services networking incorrectly, the Administration App may fail to appear. This may happen if the
network.config file is not identical on all instances. For error information, view the
/<hci-installation-directory>/config/cluster.config file or the output information logged by the run script. In both cases, you need to perform the following steps:
- Stop the run script from running by using whatever method you are currently using to run the script.
- Run this command to stop all HCI Docker containers on the instance:
sudo systemctl stop pentahoWorkerNodes.service
- Delete the contents of the
<install-path>/hci/directory from all instances.
- Begin the installation again from Unpack the Pentaho Worker Nodes Product Package.
Set Up Worker Nodes on the Pentaho Server
After packaging the Pentaho Worker Nodes Product and seeing how to apply it to a single HCI instance, see Set Up Pentaho Worker Nodes on Pentaho Server to continue the setup process