This guide consolidates every breaking change, new service, and required configuration accumulated since the 5.1.x LTS line into the single supported self-hosted upgrade path: 5.1.x → 5.9.x LTS.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.
5.9.0 is the first release in the 5.9.x LTS family (target 2026-06-02). Monthly LTS patches follow from July 2026. Direct upgrade from 5.1.x LTS to 5.9.0 is the supported self-hosted path.
What changes at a glance
New services since 5.1.x LTS
5.9.0 introduces 13 microservices that did not exist in 5.1.x. Backend microservices (4):email-gateway. Outbound email deliveryorganization-manager. Organization, workspace, and LLM configuration (absorbs the deprecatedai-platform-modelsservice)webhook-gateway. Inbound webhook intakelicense. License verification
ai-platform-ai-assistant. Replaces the 5.1.xai-assistantserviceembedder. Embedding generationknowledgebase-rag. Retrieval-augmented generation backendknowledgebase-indexer-v2. Knowledge base indexing pipeline
flowx-ai/, installed independently from the AI Platform umbrella chart:
doc-parserdoc-converterweb-crawlerdata-privacy(PII Guard)modpod
ai-assistant, ai-platform-connected-graph, ai-platform-knowledge-graph, ai-platform-agents, ai-platform-conversations, ai-platform-tenants, ai-platform-binaries, mcp, ai-platform-models. Plan their removal from your deployment manifests during the upgrade.
Supported upgrade paths
| Source version | Path | Notes |
|---|---|---|
| 5.1.x LTS | Supported | Direct upgrade from 5.1.x to 5.9.x is supported. The sections below cover the full migration. |
| Any other self-hosted source | FlowX-assisted only | Custom migration plan required. Contact your FlowX representative. |
How this guide is organized
Each section below is a self-contained topic. Read them in the order shown for a first-time upgrade; experienced operators can jump directly to the topics that affect them.Prerequisites & upgrade path
Audience, supported source versions, inventory you should gather before starting, and what FlowX assists with.
Authentication & IAM migration
Keycloak two-realm architecture, service-account client renames, opaque-token removal, SMTP configuration. The largest single break.
Runtime authorization migration
Org-level roles become project-version-scoped. End-user groups move from Keycloak into FlowX. Per-environment sharing.
Organization & deployment configuration
Single-org default mode, the
ORGANIZATION_ID Liquibase parameter on 5 services, the new license microservice, and the env-info deprecation.Kafka migration
Mandatory
Fx-Organization-Id header for every custom producer, new Kafka topics that did not exist in 5.1.x, and one topic-ownership move.Ingress routing and CORS
NGINX ingress controller deprecation, CORS handling moves to the
APPLICATION_CORS_ALLOW_ORIGIN environment variable, and the optional Gateway API HTTPRoute path.API & integration breaking changes
Endpoint rename (
get-input-json → get-start-metadata), PATCH /api/platform/environment removed, Fx-Organization-Id header mandatory, and opaque-token removal.Engine partitioning configuration
The partitioning config consolidated under
flowx.data.partitioning.archiving; the standalone SCHEDULER_DATA_PARTITIONING_* variables are gone and the archiving scheduler now defaults to off.Renderer SDK migration
Android SDK
Migrate the Android renderer from 5.1.x (9.0.x) to 5.9.x (10.x).
iOS SDK
Migrate the iOS renderer from 5.1.x to 5.9.x.
React SDK
Migrate the React renderer from 5.1.x to 5.9.x (includes React 19 upgrade).
Angular SDK
Migrate the Angular renderer from 5.1.x to 5.9.x.
What this guide assumes
- You are upgrading a self-hosted 5.1.x LTS deployment.
- You have agreed the upgrade plan with FlowX in advance. Some 5.1.x deployments may need a custom migration path that this guide does not cover; your FlowX representative will confirm the path before you start.
- You have engaged FlowX for the Liquibase migration of inactive/archived process instances. Active instances are migrated automatically; inactive ones require FlowX assistance.