Graph Modeling 10.2 to 10.3 Upgrade Guide

• Graph Modeling (formerly PoolParty): 10.3.1

• Keycloak: 2.6.0

• GraphDB: 11.4.3

• Elasticsearch: 9.3.8

If your deployment includes Add-on services, update them to the following versions:

• Semantic Workbench: 2.5.0

• ADF: 1.9.0

• GraphViews: 1.0.1

• Variables to Remove (poolparty): Remove the generic Keycloak client configurations from your configuration file (such as the .env file when deploying via Docker compose):

  POOLPARTY_KEYCLOAK_LOGIN_CLIENTID= <generic-client-id>
  POOLPARTY_KEYCLOAK_LOGIN_CLIENTSECRET= <generic-client-secret>

• Graph Modeling (poolparty) Variables: Add the new component-specific client configurations, security toggles, and split URLs:

  Component Clients:

  # PPT client configurations      
  POOLPARTY_PPT_KEYCLOAK_LOGIN_CLIENTSECRET: <ppt-secret>
  POOLPARTY_PPT_KEYCLOAK_LOGIN_CLIENTID: <ppt-id>
        
  # PPGS client configurations      
  POOLPARTY_PPGS_KEYCLOAK_LOGIN_CLIENTSECRET: <ppgs-secret>
  POOLPARTY_PPGS_KEYCLOAK_LOGIN_CLIENTID: <ppgs-id>
        
  # Extractor client configurations      
  POOLPARTY_PPX_KEYCLOAK_LOGIN_CLIENTSECRET: <ppx-secret>    
  POOLPARTY_PPX_KEYCLOAK_LOGIN_CLIENTID: <ppx-id>

  Security & Validation:

  # Audience mapping validation      
  POOLPARTY_AUTH_OPENID_REQUIRE_AUDIENCE: <boolean-value>

  Note

  The POOLPARTY_AUTH_OPENID_REQUIRE_AUDIENCE property enables audience mapping validation inside the PoolParty application for more granular control. If you use Add-ons such as ADF or Semantic Workbench set this property to false since Add-ons are not fully migrated yet and cannot be used for service account roles. If you only use core components, set this property to true to enforce strict audience validation. The default value of this property is false.

  URL Splitting:

  # Internal Docker back-channel URL (tokens, JWKS validation)
  POOLPARTY_KEYCLOAK_INTERNAL_AUTHURL="http://keycloak:8080/auth"
  
  # Public browser-facing URL (authorization, issuer, logout)
  POOLPARTY_KEYCLOAK_PUBLIC_AUTHURL="${SERVER_URL}/auth"

• Keycloak Variables: To ensure Keycloak provisions the new component clients properly during automated migration, supply the matching secrets to the Keycloak service. These must align exactly with the corresponding POOLPARTY_..._CLIENTSECRET variables used in the core application:

  • PPT_KEYCLOAK_LOGIN_CLIENTSECRET: Must match POOLPARTY_PPT_KEYCLOAK_LOGIN_CLIENTSECRET

  • PPGS_KEYCLOAK_LOGIN_CLIENTSECRET: Must match POOLPARTY_PPGS_KEYCLOAK_LOGIN_CLIENTSECRET

  • EXTRACTOR_KEYCLOAK_LOGIN_CLIENTSECRET: Must match POOLPARTY_EXTRACTOR_KEYCLOAK_LOGIN_CLIENTSECRET

• Client Secret Update: Update the OAuth2 client registration to use the new PPT specific secret:

  SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_PPT_CLIENTSECRET: 
  "${POOLPARTY_PPT_KEYCLOAK_LOGIN_CLIENTSECRET}"

• APPLICATION_VERSION: must be set to "2.5.0"

• OAuth2 URIs: Ensure the authorization and issuer URIs explicitly reference the realm variable:

  spring.security.oauth2.client.provider.keycloak.authorization-uri: 
  ${SERVER_URL}/auth/realms/${POOLPARTY_KEYCLOAK_LOGIN_REALM}/protocol/openid-connect/auth      
  
  spring.security.oauth2.resourceserver.jwt.issuer-uri: 
  ${SERVER_URL}/auth/realms/${POOLPARTY_KEYCLOAK_LOGIN_REALM}

• AUTO_MIGRATION_ENABLED: Toggles the startup migration orchestrator.

• SUPERADMIN_REQUIRES_ACTIONS: Controls mandatory password resets on the initial import of the superadmin.

• POOLPARTY_KEYCLOAK_REALM: Target realm identifier for orchestrator runs.

• TARGET_MIGRATION_VERSION, MIGRATION_BASELINE_VERSION, CURRENT_VERSION: Controls version boundaries for automated schema/realm upgrades.

• MIGRATION_TIMEOUT, MIGRATION_READINESS_TIMEOUT, MIGRATION_REALM_TIMEOUT, MIGRATION_SCRIPT_TIMEOUT, MIGRATION_LOCK_TIMEOUT: Fine-grained timeout controls for migration readiness and locks.

• MIGRATION_HEALTH_SIGNAL_FILE, MIGRATION_LOG_FILE, MIGRATION_LOG_DEBUG, MIGRATION_LOG_MAX_BYTES: Controls for logging and orchestrator health signal markers.

• Staged Startup (Without Health Checks): If your deployment environment does not support dependency healthcheck probes, you must start the services in phases:

  1. Start Infrastructure First: After having applied all necessary configurations and image upgrades, start Keycloak (2.6.0), GraphDB, and Elasticsearch. Keycloak will run the migration orchestrator automatically. Wait until Keycloak finishes migrating and is ready to accept connections.

  2. Start Core Application & Add-ons: Once Keycloak is fully migrated, start Graph Modeling (10.3.1) and your Add-on services.

• Single-Step Startup (With Health Checks: If your orchestrator (like Docker Compose or Kubernetes) uses readiness probes, you can deploy the entire stack simultaneously. The core services will wait until the Keycloak migration is complete before starting.

  Example for Docker Compose Environments:

  You can configure a health check to ensure Keycloak 2.6.0 has finished its automated migration by verifying the presence of the migration signal file before declaring the service healthy:

  services:
      keycloak:
          image: ontotext/poolparty-keycloak:2.6.0
          # ... environment variables ...
          healthcheck:
              test:
                  - "CMD-SHELL"
                  - "[ -f /opt/keycloak/data/migration_done ] && { printf 'HEAD /auth/health/ready HTTP/1.0\r\n\r\n' >&0; grep -q '200'; } 0<>/dev/tcp/localhost/9000"
              interval: 10s
              timeout: 10s
              retries: 30
              start_period: 180s
      poolparty:
          image: ontotext/poolparty:10.3.1
          # ... environment variables ...
          depends_on:
              keycloak:
                  condition: service_healthy