Semantic Workbench Installation and Upgrade

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

64-bit Linux server
OpenJDK in the same version as currently installed for your PoolParty instance
installed and configured Keycloak (with client secret for the "recommender" client);
the Semantic Workbench installer, called for instance RecommenderWorkbench_2.0.1.run
properly set up JAVA_HOME
the recommended disk space and RAM settings for Semantic 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.

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.

Elasticsearch is listening on port 9200.

Note

During both installation and update of the Semantic 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 Semantic 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 Semantic 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 Semantic Workbench as a standalone application (i.e. with its own Tomcat instance) or as an application which shares an Apache Tomcat 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 10 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 "recommender"?
>

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 Semantic Workbench instance.

STEP 8: Since we are installing the Semantic Workbench with a separate Apache Tomcat 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-10.jar
using CATALINA_OPTS:    
Tomcat started.

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

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

Note

Since the Semantic 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 Semantic Workbench.

Important

The installer of the Semantic 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

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 Semantic 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 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 Semantic Workbench as a standalone application (i.e. with its own Tomcat instance) or as an application which shares an Apache Tomcat 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 10 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 Semantic Workbench to verify that everything works as desired.

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

Note

Since the Semantic 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 Semantic Workbench.

Important

The installer of the Semantic 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.