> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Deployment guidelines v5.7.0
> Component versions, environment variables, and configuration changes for FlowX.AI 5.7.0 deployments.
After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
## Component versions
| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| -------------------------- | ------------ | -------- | ------- | ------- | ------- | ------- |
| **process-engine** | **10.96.0** | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 |
| **admin** | **10.83.0** | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 |
| **designer** | **10.164.0** | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **cms-core** | **10.58.0** | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 |
| **scheduler-core** | **10.45.0** | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 |
| **events-gateway** | **10.47.0** | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 |
| **notification-plugin** | **10.56.0** | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 |
| **document-plugin** | **10.64.0** | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 |
| **task-management-plugin** | **10.57.0** | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 |
| **data-search** | **10.44.0** | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 |
| **audit-core** | **10.54.0** | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 |
| **advancing-controller** | **10.45.0** | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 |
| **integration-designer** | **10.113.0** | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 |
| **application-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **runtime-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **data-sync** | **10.50.0** | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 |
| **authorization-system** | **10.68.0** | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 |
| **nosql-db-runner** | **10.48.0** | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 |
| **email-gateway** | **10.47.0** | 10.32.1 | 10.24.0 | 10.9.0 | - | - |
| **organization-manager** | **10.44.0** | 10.26.1 | 10.19.2 | - | - | - |
| **webhook-gateway** | **10.15.0** | 10.1.1 | - | - | - | - |
| **license** | **10.36.0** | - | - | - | - | - |
### Embedded components
* **SpiceDB**
* **DGraph**
### Renderers
| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| ----------------------------- | ------------ | -------- | ------- | ------- | ------- | ------- |
| **@flowx/angular-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |
### Plugins
| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| -------------------- | ------ | ------ | ------ | ------ | ------ | ------ |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |
### AI Platform
| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| ------------------------------- | ---------- | ------ | ------ | ------ | ------ | ------ |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 |
| **ai-platform-ai-assistant** | **10.6.2** | - | - | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 |
| **ai-platform-ai-developer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-connected-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-knowledge-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agents** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-conversations** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-tenants** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-planner** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-analyst** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-designer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agent-builder** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-binaries** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **embedder** | **10.6.2** | - | - | - | - | - |
| **knowledgebase-rag** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **mcp** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **doc-converter** | **10.2.3** | 10.2.2 | - | - | - | - |
| **doc-parser** | **10.6.2** | 10.5.1 | - | - | - | - |
| **web-crawler** | **10.3.2** | - | - | - | - | - |
| **data-privacy** | **10.0.8** | - | - | - | - | - |
| **speech-to-text** | **10.3.3** | - | - | - | - | - |
| **modpod** | **10.0.7** | - | - | - | - | - |
**Note:** The `ai-platform-models` service has been removed in 5.7.0. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers) within the Organization Manager.
***
## Third-party recommended component versions
| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.7.0 | Keycloak | 26+ |
| 5.7.0 | Kafka | 3.8 - 3.9 |
| 5.7.0 | PostgreSQL | 16 - 17 |
| 5.7.0 | Oracle Database | 21c, 23ai |
| 5.7.0 | MongoDB | 7 - 8 |
| 5.7.0 | Redis | 7.4 - 8.0 |
| 5.7.0 | Elasticsearch | 8 |
| 5.7.0 | Angular (Web SDK) | 20 |
| 5.7.0 | React (Web SDK) | 18.x |
The following versions of third-party dependencies are no longer supported:
* Keycloak versions older than 26
* Kafka versions older than 3.8
* Redis versions older than 7.4
***
## Self-hosted deployment changes
**First on-premises release since 5.4.0.** This section covers critical configuration changes for self-hosted (on-premises) deployments.
### Supported upgrade paths
| Source version | Path | Notes |
| ----------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Fresh install** | Supported | Guided setup flow on first launch. See [Organization Manager setup](/5.1/setup-guides/organization-manager-setup). |
| **5.1.x LTS** | Supported | Requires Organization ID on all 19 services. Liquibase migrates active process instances and realm data. Inactive instances require separate handling by FlowX. See details below. |
| **5.2 - 5.4** | FlowX-assisted only | These versions may have partial realm or organization changes. Contact your FlowX representative for a custom migration plan. Do **not** follow the 5.1.x upgrade path. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |
### Organization ID (mandatory for upgrades)
The Organization ID is how FlowX identifies your installation. How it is obtained depends on your deployment path:
* **Fresh install:** The Organization ID is created automatically during the guided setup flow (Designer first-launch screen). No manual configuration needed.
* **Upgrade from 5.1.x:** FlowX registers your organization in the SaaS licensing infrastructure and provides an Organization ID (UUID). Set `ORGANIZATION_ID` on **all 19 services** before deploying 5.7.0 images — Liquibase migrations use it to replace the default organization.
```yaml theme={"system"}
# Example — set on every service
ORGANIZATION_ID: "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx" # UUID provided by FlowX
```
**Affected services (all 19):** process-engine, admin, audit-core, authorization-system, advancing-controller, events-gateway, cms-core, scheduler-core, data-search, document-plugin, nosql-db-runner, notification-plugin, task-management-plugin, integration-designer, organization-manager, email-gateway, application-manager, runtime-manager, license.
Do **not** deploy 5.7.0 images without setting `ORGANIZATION_ID` on upgrade scenarios. Services will fail to start if Liquibase migrations cannot find the organization ID.
**Active vs inactive instances.** Liquibase migrations automatically update the Organization ID on **active process instances** only. Inactive or archived instances require separate migration handled by the FlowX team during guided deployment. Contact your FlowX representative for details.
### License service (new)
Self-hosted deployments must configure the License service to connect to FlowX SaaS for license validation and usage reporting. See the [License service setup guide](/5.9/setup-guides/license-engine-setup) for complete configuration.
### IAM / Keycloak changes
FlowX.AI now uses a **two-realm architecture** in Keycloak and **JWT public key validation** (replacing opaque-token introspection). These changes were introduced in 5.5.0 (SaaS) and are now relevant for self-hosted deployments.
* **Token validation**: `security.type` switches from `oauth2` to `jwt-public-key` on all services
* **Service accounts realm**: A dedicated realm (`00000002-0002-4002-8002-000000000002`) holds all service account clients, separate from the user realm
* **Organization manager**: Now a required dependency for all services (provides realm resolution)
* **`flowx-platform-authorize` client**: No longer needed — remove from Keycloak
* **Master realm credentials**: The authorization-system service needs Keycloak admin access for realm migrations. If you cannot provide admin credentials, see [Manual Keycloak configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).
* **SMTP**: Must be configured in Keycloak for password reset and user invitations
For complete IAM setup instructions, see the [Configuring an IAM solution](/5.1/setup-guides/access-management/configuring-an-iam-solution) guide.
***
## Environment info deprecation
The **Configure Environment Info** feature (`PATCH /api/platform/environment`) is deprecated and removed. Environment name is now set during organization registration. The following are no longer used:
* `FLOWX_CLIENT_NAME` environment variable
* `FLOWX_ENVIRONMENT_NAME` environment variable
* `environmentDetails` section in the `/api/init` response
***
## Kafka integration changes
### Fx-Organization-Id header (mandatory)
All FlowX Kafka consumers now validate the `Fx-Organization-Id` header on every incoming message. Messages without this header are rejected with a non-retryable `MissingKafkaHeaderException`.
**Action required for custom Kafka integrations.** If you have custom Kafka producers that publish directly to FlowX topics (starting processes, sending task events, responding to engine requests), you must add the `Fx-Organization-Id` header to every message. Set it to the Organization UUID (`ORGANIZATION_ID` value).
```java theme={"system"}
producerRecord.headers().add("Fx-Organization-Id",
organizationId.getBytes(StandardCharsets.UTF_8));
```
See the [Creating a Kafka producer](/5.1/docs/platform-deep-dive/integrations/creating-a-kafka-producer#the-fx-organization-id-header) guide for details.
### New Kafka topics
| Topic | Environment Variable | Producer | Consumer | Description |
| -------------------------------- | -------------------------------- | -------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------ |
| `ai.flowx.llm.config.changed.v1` | `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | organization-manager | integration-designer, AI Python services | Broadcast when LLM provider or model configuration changes at the organization level |
***
## Environment variables
Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).
### New environment variables
| Environment Variable | Description | Default Value | Component |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `ORGANIZATION_ID` | Organization UUID provided by FlowX. Required on all services for upgrades. Fresh installs get this automatically via the setup flow. | - | all services |
| `FLOWX_LICENSE_KEY` | License key for FlowX SaaS connection | - | license |
| `FLOWX_LICENSE_AUTHSERVERURL` | FlowX SaaS auth URL | - | license |
| `FLOWX_LICENSE_SERVERURL` | FlowX SaaS license API URL | - | license |
| `FLOWX_ORG_MANAGER_URL` | Organization Manager service URL for LLM provider configuration. Required on all Python AI services. | - | planner, ai-developer, ai-analyst, ai-designer, agent-builder, knowledgebase-rag, embedder, knowledgebase |
| `SECURITY_MASTERREALM_CLIENTID` | Master realm admin client ID for Keycloak management | `admin-cli` | authorization-system |
| `SECURITY_MASTERREALM_NAME` | Keycloak master realm name | `master` | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_USERNAME` | Keycloak admin username for realm migrations | - | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_PASSWORD` | Keycloak admin password for realm migrations | - | authorization-system |
| `SECURITY_OAUTH2_SAREALM` | Service accounts realm ID | `00000002-0002-4002-8002-000000000002` | all services |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | Organization manager URL for security lib | `http://organization-manager:80` | all services |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_RESPONSETIMEOUT` | Response timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `60` | organization-manager |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_CONNECTIONTIMEOUT` | Connection timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `30` | organization-manager |
| `FLOWX_SPEECH_TO_TEXT_BASE_URL` | Base URL for the Speech-to-Text service | `http://speech-to-text:80` | integration-designer |
| `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | Topic for LLM config change notifications | `ai.flowx.llm.config.changed.v1` | organization-manager |
| `LLM_ENCRYPTION_MASTER_KEY` | Encryption key for LLM provider API keys at rest. **Change from default in production.** | `default-dev-key-change-in-prod` | organization-manager |
| `FLOWX_DEFAULT_DESIGNER_HOME_URI` | Base URL of the Designer web app. Required on on-prem deployments. | - | organization-manager |
| `FLOWX_DEFAULT_RUNTIME_HOME_URI` | Base URL of the Runtime (generic container) web app. Required on on-prem deployments when the FlowX generic container app is deployed. | - | organization-manager |
| `FLOWX_DEFAULT_SECURITY_REALM_ALLOWED_REDIRECT_URIS` | Comma-separated list of additional Keycloak redirect URIs. If empty, derived automatically from `FLOWX_DEFAULT_DESIGNER_HOME_URI` and `FLOWX_DEFAULT_RUNTIME_HOME_URI` with a `/*` suffix. Override only to allow access from another app, or when using Keycloak login inside a client-owned container app that uses the FlowX SDK. | `[]` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_ACCOUNT_VERIFICATION` | Lifespan of the account verification link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_USER_INVITE` | Lifespan of the user invite link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_FORGOT_PASSWORD` | Lifespan of the forgot-password link sent by email, in seconds. | `3600` | organization-manager |
| `DEFAULT_ORGANIZATION_NAME` | Fallback organization code used by the Designer web app during Keycloak authentication when no `organizationCode` URL query parameter or subdomain is present. Required on on-prem — set to the organization code registered with FlowX. | - | designer |
| `FLOWX_SQL_DISCOVERY_CACHE_TTL` | Time-to-live for Oracle Database schema discovery responses cached for the SQL editor. | `24h` | integration-designer |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum cached JDBC connection pools used by Oracle Database data sources. | `100` | nosql-db-runner |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL` | Time-to-live for cached JDBC connection pools. | `1d` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE` | Maximum HikariCP pool size per Oracle Database data source. | `5` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout for Oracle Database data sources. | `10` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT` | Default row cap on `SELECT` responses for Oracle Database operations. | `1000` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS` | Query execution timeout for Oracle Database operations. | `30` | nosql-db-runner |
### Removed environment variables
**For upgrades:** Remove these variables only **after** the Liquibase migrations have completed successfully. If you remove them before starting services for the first time on 5.7.0, the migrations may fail. The recommended sequence is: (1) add new variables, (2) deploy 5.7.0 images, (3) let migrations run, (4) verify services are healthy, (5) remove old variables in a follow-up deployment.
| Environment Variable | Reason | Component |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `FLOWX_CLIENT_NAME` | Replaced by org code from registration | process-engine |
| `FLOWX_ENVIRONMENT_NAME` | Replaced by env name from registration | process-engine |
| `AI_SERVICE_MODELS_ENDPOINT` | The Models microservice (port 9104) has been removed. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers). Remove this service from your deployment. | ai-platform (all Python services) |
| `SECURITY_OAUTH2_REALM` | Replaced by per-organization realm resolution. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTID` | Opaque-token introspection client no longer needed. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTSECRET` | Opaque-token introspection client secret no longer needed. | all services |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_*` | Entire opaque-token introspection config removed. | all services |