> ## 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.
# Prerequisites & upgrade path
> Audience, supported source versions, and the inventory you should gather before starting the 5.1 LTS → 5.9 LTS upgrade.
## 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](./organization-deployment#organization_id--where-it-is-actually-required) 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:
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](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) after the upgrade.
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.
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](./authentication-iam).
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.
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.
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.
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](#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.
| Dependency | Dropped versions | Minimum supported in 5.9.0 |
| ---------- | ----------------------- | -------------------------- |
| Kafka | 3.8 and older | 3.9 |
| Redis | Versions older than 8.2 | 8.2 |
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](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9#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:
| Dependency | Used by |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Qdrant** | Knowledge Base infrastructure (vector storage) |
| **SpiceDB** | Expanded coverage on 5.9.x — `data-search` and `email-gateway` join the existing SpiceDB consumers |
| **Kafka Connect (Strimzi) + Elasticsearch Sink Connector** | Process-engine indexing into Elasticsearch via Kafka. Required only if you enable `FLOWX_INDEXING_TYPE=kafka`. See [Configuring Elasticsearch indexing](/5.9/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing). |
| **Outbound HTTPS to FlowX SaaS** | `license` service (license validation, usage reporting) |
| **SMTP server** | Keycloak (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:
| Service | Purpose | Setup guide |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **webhook-gateway** | Receives incoming HTTP webhooks from external systems and routes them to processes via Kafka | [Webhook Gateway setup](/5.9/setup-guides/webhook-gateway-setup) |
| **email-gateway** | IMAP/Outlook email trigger and sender for processes and workflows | [Email Gateway setup](/5.9/setup-guides/email-gateway-setup) |
| **file-gateway** | Ingests files from FTP/SFTP/S3/Azure Blob and delivers generated files back; can trigger processes when new files arrive | [File Gateway setup](/5.9/setup-guides/file-gateway-setup) |
| **ai-gateway** | Powers the AI chat experience in FlowX Designer, streaming AI assistant responses to the browser and routing requests to the AI agents | [AI Gateway setup](/5.9/setup-guides/ai-gateway-setup) |
| **license** | License validation and usage reporting (requires outbound HTTPS to FlowX SaaS) | [License setup](/5.9/setup-guides/license-engine-setup) |
| **organization-manager** | Organization and multi-tenancy management | [Organization Manager setup](/5.9/setup-guides/organization-manager-setup) |
| **authorization-system** | Fine-grained authorization via SpiceDB | [Authorization System setup](/5.9/setup-guides/authorization-setup-guide) |
The **AI Platform** is also new on 5.9.x. If your deployment uses AI features, refer to the [AI Platform setup](/5.9/ai-platform/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](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) 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
Start with this. It is the largest single break.
Project-scoped roles, end-user groups, per-environment sharing.