PoolParty Workbench Installation and Upgrade

Introduction and Prerequisites

The installer for PoolParty Workbench only runs on a Linux system. The following prerequisites must be satisfied for running the installation procedure:

64bit GNU/Linux Server (Debian 12 preferably)
OpenJDK in the same version as currently installed for your PoolParty instance (currently supported are OpenJDK 17 and 21)
installed and configured Keycloak (with client secret for the "recommender" client); PoolParty 2024 Release 2 installation includes Keycloak version 25.0.6
the PoolParty Workbench installer, called for instance RecommenderWorkbench_2.0.1.run
properly set up JAVA_HOME
the recommended disk space and RAM settings for PoolParty Workbench are: min 5 GB disk space and min 4 GB RAM (Apache Tomcat requirement)

Tip

The client secret value for the Keycloak "recommender" client can be accessed in Keycloak, where you are automatically redirected to the Administration Console. There go to Clients and select the client "recommender"; subsequently click on the Credentials tab where you can see the client secret value for the selected Keycloak client; you can also regenerate this value, if required.

Note

Please note that Solr supported is being deprecated with the current version, i.e. PoolParty 2024 Release 2; starting from the next version - PoolParty Release 3 - only Elasticsearch will be supported. Please make sure to correspondingly migrate your index from Solr to Elastic search - for more details refer to Migrating Index from Solr to Elasticsearch on Linux and Switching from Solr to Elasticsearch in PoolParty

Caution

It is recommended to run the installation as a root user to ensure smooth installation process and avoid any permission issues during the installation procedure.

Note

Default ports used by PoolParty installation:

Apache Tomcat will be running as localhost using port 8081.

Keycloak will be running as localhost using port 8181.

The built-in Apache Solr server will be running as localhost using port 8983.

Elasticsearch is listening on port 9200.

Note

During both installation and update of the PoolParty Workbench instance you will be prompted to specify the path to the PoolParty license which may look like this /opt/poolparty/config.

Note

If you are installing a new version of Tomcat you will always have to manually stop Tomcat prior to running the installation or upgrade as well as restart it manually after having completed the installation or upgrade.

STEP 1: Open the terminal and run there the installer RecommenderWorkbench_2.0.1.run. At first you will be prompted that PoolParty Workbench will be installed on your system. To confirm press either o or Enter. If you want to cancel the installation press c.

STEP 2: Now you are presented two options for your installation - you can either install a new or upgrade the PoolParty Workbench instance. Start a new installation by either entering 1 or pressing Enter.

This will install RecommenderWorkbench 2.0.1 on your computer.
OK [o, Enter], Cancel [c]
>
Choose the appropriate option:
Install RecommenderWorkbench [1, Enter],
Upgrade an existing RecommenderWorkbench installation [2],
Cancel installation [c]
>

STEP 3: Now you are prompted to specify whether you want to install the Workbench as a standalone application (i.e. with its own Tomcat instance) or as an application which shares an Apache Tomcat 9 instance. Press 1 or Enter to continue with the first option.

Choose the appropriate option:
RecommenderWorkbench is run as a standalone application [1, Enter],
RecommenderWorkbench is run on a shared Tomcat 9 instance (this will not update Tomcat) [2],
Cancel installation [c]
>

STEP 4 : Now you will specify the directory where the Workbench will be installed along with the default Workbench user and group:

Where should RecommenderWorkbench be installed
[/opt/recommenderworkbench]
>
Default RecommenderWorkbench user:
[poolparty]
>
Default RecommenderWorkbench group:
[poolparty]
>

STEP 5: Now you are prompted to review the settings you just made. If everything is OK, proceed with the installation by pressing o or Enter , press c to cancel and change these settings as required.

STEP 6: Now you need to enter the URLs to the PoolParty and Keycloak instances to be used. Let us use the default settings here, for instance a https://your.poolparty.server:port and https://<KEYCLOAK_URL>:KEYCLOAK_PORT. Then specify the realm to be used in the Keycloak instance (default poolparty ) and the enter the client secret value of the Keycloak client "recommender".

What is the URL to the PoolParty instance to use? (e.g.: http://test.poolparty.biz)
>
What is the path to the PoolParty license? (e.g.: /opt/poolparty/config/licenses)
>
What is the URL to the Keycloak instance to use? (e.g. https://<KEYCLOAK_URL>[:8181])
>
What is the Realm in the Keycloak instance to use? (e.g poolparty)
>
What is the Client Secret of Keycloak Client "recommender2?
>

Note

You have to provide the absolute path to the directory containing the PoolParty license.

The Client Secret value of the Keycloak client can be retrieved from the respective tab in Keycloak.

STEP 7: Review the settings again and proceed by pressing o or Enter, respectively press c and make any required adjustments to these settings.

In this step press o. or Enter to run the install script and install the PoolParty Workbench instance.

STEP 8: Since we are installing the PoolParty Workbench with a separate Apache Tomcat 9.x instance you will need to manually start Tomcat after having completed the installation. This may look like this:

ROOT-SURFACE:           /opt/recommenderworkbench/bin# ./startup.sh
using CATALINA_BASE:    /opt/recommenderworkbench
using CATALINA_HOME:    /opt/recommenderworkbench
using CATALINA_TMPDIR:  /opt/recommenderworkbench/temp
using JRE_HOME:         /usr
using CLASPATH:         /opt/recommenderworkbench/bin/boostrap.jar:/opt/
recommenderworkben/bin/tomcat-9.jar
using CATALINA_OPTS:    
Tomcat started.

STEP 9: Start the PoolParty Workbench to verify that everything works as desired.

Open a browser and access your PoolParty Workbench installation at your.poolparty.server/RecommenderWorkbench. You will have to log in using your user credentials set in PoolParty.

Note

Since the PoolParty Workbench relies on PoolParty for user management, you need to have a PoolParty user account in place. The same user credentials are used for accessing the PoolParty and the Workbench.

Important

The installer of the PoolParty Workbench creates the entire directory structure including the /recommenderworkbench/data/ directory where the database storing all configurations is located. Currently you will have to manually back up this directory before installing a new Tomcat or PoolParty version since such upgrade/installation will overwrite this directory. The easiest way is to copy the directory to a desired backup location using the cp command.

The upgrade procedure is very similar to the initial installation process. The only thing to keep in mind is to back up the /recommenderworkbench/data/ directory where the database storing all recommender configurations is located, if the upgrade includes a new version of Tomcat.

Important

STEP 2: Now you are presented two options for your installation - you can either install a new or upgrade the Workbench instance. Start the upgrade by entering 2.

This will install RecommenderWorkbench 2.0.1 on your computer.
OK [o, Enter], Cancel [c]
>
Choose the appropriate option:
Install RecommenderWorkbench [1, Enter],
Upgrade an existing RecommenderWorkbench installation [2],
Cancel installation [c]
>

STEP 3: Now you are prompted to specify whether you want to upgrade the PoolParty Workbench as a standalone application (i.e. with its own Tomcat 9.x instance) or as an application which shares an Apache Tomcat 9 instance. Press 1 or Enter to continue with the first option since our original installation was as a standalone application.

Choose the appropriate option:
RecommenderWorkbench is run as a standalone application [1, Enter],
RecommenderWorkbench is run on a shared Tomcat 9 instance (this will not update Tomcat) [2],
Cancel installation [c]
>

STEP 4: Now you are prompted to review the settings made during the initial installation. If everything is OK, proceed with the upgrade by pressing o or Enter , press c to cancel and change these settings as required.

STEP 5: After completing the upgrade launch the PoolParty Workbench to verify that everything works as desired.

Open a browser and access your PoolParty Workbench installation at your.poolparty.server:port/RecommenderWorkbench. You will have to log in using your user credentials set in PoolParty.

Note

Important

In this section: