Skip to main content

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.

​
Audience and scope

This guide is for operators of self-hosted FlowX.AI 5.1.x LTS deployments upgrading to 5.9.x LTS. The 5.9.x LTS family opens with 5.9.0 (target 2026-06-02) and continues with monthly LTS patches from July 2026 onward.
  • In scope: Self-hosted deployments running any 5.1.x patch level.
  • Out of scope: SaaS deployments. They are continuously upgraded on the SaaS line and do not perform this migration. Any other self-hosted source version requires a FlowX-assisted custom migration plan.
The upgrade jumps directly from the 5.1.x LTS line to the 5.9.x LTS line.
Confirm your upgrade plan with FlowX before starting. Some 5.1.x deployment configurations require a custom migration path that this guide does not cover. Your FlowX representative will validate compatibility and provide any tailored migration scripts ahead of the upgrade window.

​
Get your Organization UUID

FlowX issues an Organization UUID when your organization registers with FlowX SaaS for license validation and usage reporting. Request it from your FlowX representative before the upgrade window starts. You will need this single UUID for:
  • The ORGANIZATION_ID Liquibase parameter on 9 services (application-manager, authorization-system, cms-core, document-plugin, integration-designer, notification-plugin, organization-manager, process-engine, scheduler-core). See Organization & deployment configuration for the full behavior.
  • The FLOWX_LICENSE_ORGANIZATION_ID runtime env var on the license service (OAuth client-id for the FlowX SaaS license handshake. Different env var, same UUID value).
  • The Fx-Organization-Id Kafka header on every custom producer.

​
Inventory to gather

Before the upgrade window, capture the following from your current 5.1.x deployment:
1

Current component versions

Open FlowX.AI Designer → Platform Status and record the version of each FlowX component. You will compare these against the 5.9.x targets in the v5.9.0 deployment guidelines after the upgrade.
2

Current SDK versions

List the @flowx/* web SDK package versions in each container app, plus the iOS and Android renderer versions. iOS and Android renderers ship on the 9.0.x line in 5.1.x; 5.9.x targets the 10.x line. Web @flowx/* packages follow the Designer version baseline, not the renderer 9/10 numbering.
3

Keycloak realms and clients

Export the list of realms, clients, client scopes, and protocol mappers from your current Keycloak. 5.9.x introduces a dedicated service-accounts realm and renames every service-account client to a flowx-{service}-sa pattern. See Authentication & IAM migration.
4

Kafka topic ACLs and custom producers

If you manage Kafka topic ACLs manually, list every topic and its producers/consumers. The WorkspaceCreatedEvent topic ownership changes on 5.9.x. List every custom Kafka producer your team operates. Each must add the Fx-Organization-Id header on 5.9.x.
5

Custom API clients

Identify any internal tooling that calls:
  • GET /api/process-definition/{uuid}/get-input-json. Renamed to /get-start-metadata on 5.9.x.
  • PATCH /api/platform/environment. Removed on 5.9.x.
  • Any client that reads environmentDetails from /api/init. Field is deprecated on 5.9.x; its values now come from organization registration rather than the legacy FLOWX_CLIENT_NAME / FLOWX_ENVIRONMENT_NAME env vars. Migrate clients off this field.
6

Partitioning configuration

If you enabled data partitioning on 5.1.x, capture the current scheduler.dataPartitioning YAML block and the five related env vars. The structure and names change on 5.9.x; your FlowX representative will share the new YAML during the upgrade plan.
7

Backups

Take fresh backups of:
  • All Postgres databases (per-service).
  • All MongoDB databases (per-service).
  • Keycloak realm exports.
  • SpiceDB schema and relations.
Rollback paths after the 5.9.x schema migrations (organization-manager, runtime authorization tables) require restore from backup. See Rollback considerations below.
Carry forward every required configuration from your 5.1.x deployment. This guide documents what changes on 5.9.x; it does not re-list every configuration value your services already require. Values your 5.1.x services depend on — such as SpiceDB connection and credentials, Redis, and database settings — remain required on 5.9.x and must be carried over. If a service fails to start and its logs report a missing configuration, that value is required: take it from your existing 5.1.x configuration.

​
Dropped third-party dependency versions

The following third-party versions are no longer supported in 5.9.0. Upgrade them before the FlowX 5.9 upgrade window — running an unsupported version after the FlowX upgrade is not covered by the standard support process.
DependencyDropped versionsMinimum supported in 5.9.0
Kafka3.8 and older3.9
RedisVersions older than 88
Versions are dropped from the supported list as upstream support is no longer provided. For the full supported-version matrix (Keycloak, PostgreSQL, MongoDB, Oracle, Elasticsearch Sink Connector, renderer SDKs), see the v5.9.0 deployment guidelines — Third-party recommended component versions.

​
Infrastructure deltas

The 5.1 → 5.9 jump adds several runtime dependencies your 5.1.x environment may not already have:
DependencyUsed by
QdrantKnowledge Base infrastructure (vector storage)
SpiceDBExpanded coverage on 5.9.x — data-search and email-gateway join the existing SpiceDB consumers
Kafka Connect (Strimzi) + Elasticsearch Sink ConnectorProcess-engine indexing into Elasticsearch via Kafka. Required only if you enable FLOWX_INDEXING_TYPE=kafka. See Configuring Elasticsearch indexing.
Outbound HTTPS to FlowX SaaSlicense service (license validation, usage reporting)
SMTP serverKeycloak (password reset, user invitations)

​
New services to deploy

5.9.x ships several microservices that do not exist in a 5.1.x deployment. Ensure Helm charts and infrastructure are provisioned for these before upgrading:
ServicePurposeSetup guide
webhook-gatewayReceives incoming HTTP webhooks from external systems and routes them to processes via KafkaWebhook Gateway setup
email-gatewayIMAP/Outlook email trigger and sender for processes and workflowsEmail Gateway setup
file-gatewayIngests files from FTP/SFTP/S3/Azure Blob and delivers generated files back; can trigger processes when new files arriveFile Gateway setup
ai-gatewayPowers the AI chat experience in FlowX Designer, streaming AI assistant responses to the browser and routing requests to the AI agentsAI Gateway setup
licenseLicense validation and usage reporting (requires outbound HTTPS to FlowX SaaS)License setup
organization-managerOrganization and multi-tenancy managementOrganization Manager setup
authorization-systemFine-grained authorization via SpiceDBAuthorization System setup
The AI Platform is also new on 5.9.x. If your deployment uses AI features, refer to the AI Platform setup guide for the full list of AI services (agent-builder, knowledgebase-rag, embedder, and others) and their infrastructure requirements (Qdrant and S3).The AI Platform also ships a versioned documentation image (flowx-docs:5.9.0) that is mounted into the AI Assistant so it can answer from the FlowX documentation. It is a content image, not a standalone service; pull the version matching your release (see the component versions in the deployment guidelines).
Confirm minimum versions against the v5.9.0 deployment guidelines Third-party recommended component versions table before scheduling the upgrade window.

​
Rollback considerations

Not every change in the 5.1 → 5.9 upgrade is reversible by configuration alone.
  • Partitioning configuration rename. Configuration-only. Reverting the new partitioning.archiving block back to scheduler.dataPartitioning restores the previous behavior; the database schema is forward-compatible.
  • organization-manager service. Adds new PostgreSQL schemas. Rollback requires database backup restore.
  • Keycloak two-realm transition. Service-account clients and realm structure change. Rollback requires restoring Keycloak from realm export and reverting the service-account client IDs.
  • Runtime authorization. End-user groups move from Keycloak to FlowX. Sharing assignments are FlowX-side records that have no Keycloak equivalent to roll back to.
Plan the upgrade window with the assumption that rolling back to 5.1.x requires a full backup restore. Confirm restoration procedures during pre-upgrade rehearsal.

​
Next

Authentication & IAM migration

Start with this. It is the largest single break.

Runtime authorization migration

Project-scoped roles, end-user groups, per-environment sharing.
Last modified on June 2, 2026