- Graphwise Documentation - General
- How to Install & Manage Graphwise Components
- Installation & Migration
- Semantic Workbench Installation and Upgrade
Semantic Workbench Installation and Upgrade
03/10/2025
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.runproperly set up
JAVA_HOMEthe 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.