Semantic Workbench Installation and Upgrade Guide

13/07/2026

This guide summarizes the installation and upgrade procedures for the Semantic Workbench. Steps for how to uninstall and troubleshoot the Semantic Workbench are also listed below.

Note

For more information on how to migrate already existing Semantic Workbench data to version 2.4.0, visit this dedicated help page.

The Semantic Workbench (formerly known as PoolParty Workbench) is a powerful Spring Boot application designed for efficient management of PoolParty taxonomies. It empowers subject-matter experts to optimize their semantic workflows through intuitive parameter configuration for inference tagging and recommender features.

Starting with version 2.4.0, the Semantic Workbench is deployed using a fully cloud-native approach via Helm charts on Kubernetes. The previous installation method using download scripts and standalone WAR files has been replaced by a Dockerized, Helm-managed deployment.

Component	Details
Helm Chart Version	0.1.2
Application Version	2.4.1
Minimum Kubernetes Version	1.32+
Image Registry	`docker.io`
Image Repository	`ontotext/semantic-workbench`
License	Apache 2.0

Prerequisites

Before installing the Semantic Workbench, ensure the following requirements are met:

Kubernetes v1.32 or later
Helm v3.18 or later
kubectl configured to communicate with your cluster
A running instance of PoolParty
A valid PoolParty license file (poolparty.key)
A running Keycloak instance configured with the appropriate realm and client for authentication

Dependencies

The Semantic Workbench requires a running PoolParty instance to connect to and extend. For details about PoolParty installation, refer to the PoolParty Helm chart documentation.

Important

Starting with Semantic Workbench 2.5.0 and ADF 1.9.0, the single KEYCLOAK_URL variable is deprecated and now maps exclusively to internal traffic.

To resolve past OAuth redirect issues, Keycloak network traffic has been split. The following variables can now be used instead:

KEYCLOAK_PUBLIC_URL: Used for browser-facing actions (authorization, issuer, logout).
KEYCLOAK_INTERNAL_URL: Used for back-channel service communication (tokens, JWKS validation).

Details can be found in the addons.yaml and .env_template files in the compose-files repository.

Create the License Sheet: The Semantic Workbench requires a valid PoolParty license. Create a Kubernetes Secret containing your license file:
```
kubectl create secret generic poolparty-license --from-file poolparty.key=/path/to/poolparty.key
```
Note
The license file will be mounted at /usr/share/semantic-workbench/licenses inside the container by default. This path can be changed via license.mountPath in the Helm values.

Add the Helm Repository:

Add the Semantic Workbench Helm chart repository and update your local cache:

helm repo add poolparty-semantic-suite https://poolparty-semantic-suite.github.io/charts
helm repo update

Create a values-override.yaml file with the configuration values specific to your environment:

license:
  existingSecret: poolparty-license

configuration:
  externalUrl: http://semantic-workbench.your-domain.com/SemanticWorkbench
  properties:
    POOLPARTY_URL: http://your-poolparty-instance:8080
    KEYCLOAK_URL: http://your-keycloak-instance/auth
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_PPT_CLIENTSECRET: <your-client-secret>

The following configuration properties are required:

Property	Description	Example
`configuration.properties.POOLPARTY_URL`	URL of your PoolParty instance (without`/PoolParty`suffix)	`http://poolparty.example.com`
`configuration.properties.KEYCLOAK_URL`	URL of your Keycloak instance	`http://keycloak.example.com/auth`
`configuration.properties.SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_PPT_CLIENTSECRET`	Keycloak client secret for authentication	`ohIP3x4XuoCsGDsGlZRvNvO5VN6veFb5`
`license.existingSecret`	Name of the Kubernetes Secret containing the license	`poolparty-license`

The following configuration properties are optional and have predefined defaults:

Property	Default	Description
`configuration.externalUrl`	`http://semantic-workbench.127.0.0.1.nip.io/SemanticWorkbench`	External URL where the application can be accessed
`configuration.properties.SPRING_DATASOURCE_URL`	`jdbc:sqlite:/app/data/sqlite_semantic_workbench.db`	Database connection string
`configuration.defaultJavaArguments`	`-XX:MaxRAMPercentage=85`	Default JVM arguments

Install the Chart:

Install the Semantic Workbench using Helm:

helm install semantic-workbench poolparty-semantic-suite/workbench -f values-override.yaml

Alternatively, provide values inline using --set:

helm install semantic-workbench \
  --set license.existingSecret=poolparty-license \
  --set configuration.properties.POOLPARTY_URL=http://your-poolparty-instance:8080 \
  --set configuration.properties.KEYCLOAK_URL=http://your-keycloak-instance/auth \
  --set configuration.properties.SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_PPT_CLIENTSECRET=<your-client-secret> \
  poolparty-semantic-suite/workbench

Verify the Installation:
Wait for the pods to become ready and verify the deployment:
```
kubectl get pods -l app.kubernetes.io/name=semantic-workbench
```

Application Properties

Most configuration properties can be passed through the configuration.properties section in your values file. These are injected as environment variables into the container via a ConfigMap. For a full list of configurable values, refer to the values.yaml file or run:

helm show values poolparty-semantic-suite/workbench

Sensitive Properties

For sensitive values such as client secrets and database passwords, use a Kubernetes Secret instead of plain-text.

ConfigMap values:

configuration:
  propertiesOverrides:
    existingSecret: my-secret-workbench-properties

Create the secret as follows:

kubectl create secret generic my-secret-workbench-properties \
  --from-literal=SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_PPT_CLIENTSECRET=<your-client-secret>

Custom Logback Configuration

To override the default logging configuration, supply your own logback.xml via a ConfigMap:

Create a ConfigMap with your Logback configuration:

kubectl create configmap workbench-logback --from-file=logback.xml=/path/to/logback.xml

Reference the ConfigMap in your values:

configuration:
  logback:
	existingConfigmap: workbench-logback
  javaArguments: "-Dlogging.config=/var/lib/semantic-workbench/config/logback.xml"

Ingress

By default, the Helm chart deploys an Ingress resource. The Ingress hostname and path are derived from configuration.externalUrl.

To use a specific Ingress controller:

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"

To enable TLS:

ingress:
  tls:
    enabled: true
    secretName: semantic-workbench-tls

configuration:
  externalUrl: https://semantic-workbench.your-domain.com/SemanticWorkbench

To disable the default Ingress entirely:

ingress:
  enabled: false

Persistence

Persistence is enabled using a PersistentVolumeClaim with 5Gi of storage by default. The SQLite database is stored at /var/lib/semantic-workbench.

To customize storage:

persistence:
  enabled: true
  volumeClaimTemplate:
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 10Gi

Warning

Disabling persistence will result in data loss when pods are restarted or terminated.

Resources

Default resource limits are provided for initial deployments. For production environments, review and adjust these values according to your workload:

resources:
  limits:
    memory: 5Gi
  requests:
    memory: 4Gi
    cpu: 500m

Helm Chart Upgrade

This procedure summarizes how to upgrade to a newer version of the Semantic Workbench Helm chart.

Update your Helm repository:
```
helm repo update
```
Review the CHANGELOG.md and UPGRADE.md for any breaking changes.

Perform the upgrade:

helm upgrade semantic-workbench poolparty-semantic-suite/workbench -f values-override.yaml

Verify the upgrade:

kubectl get pods -l app.kubernetes.io/name=semantic-workbench
curl http://<your-external-url>/SemanticWorkbench/actuator/health

Version Compatibility

Helm Chart Version	Semantic Workbench Version
0.1.x	2.3.x

Connection Issues

If connections time out or the pods cannot resolve each other, it is likely that the Kubernetes DNS is broken. This is a common issue with Minikube between system restarts or when an inappropriate Minikube driver is used. Refer to Debugging DNS Resolution.

Filesystem Provisioning Errors (Multi-Node Minikube Cluster)

When expanding your Minikube cluster from one to two or more nodes, you may encounter errors when setting up persistent storage. These issues are due to implementation problems with the storage provisioner included with Minikube. Follow the steps outlined in the CSI Driver and Volume Snapshots documentation, specifically in the "Multi-Node Clusters" section.

Checking Application Logs

# View pod logs
kubectl logs -l app.kubernetes.io/name=semantic-workbench

# Follow logs in real-time
kubectl logs -f -l app.kubernetes.io/name=semantic-workbench

Pod Startup Issues

If the pod fails to start, check the events:

kubectl describe pod -l app.kubernetes.io/name=semantic-workbench

Common causes include:

Missing or invalid license secret
Incorrect PoolParty or Keycloak URLs
Insufficient resources (memory/CPU)
PersistentVolume provisioning failures

In this section: