> ## 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_ORGANIZATIONID` 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. 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. These backups are the only way back. There is no in-place downgrade from 5.9.x to 5.1.x — reverting means restoring every one of these stores to its pre-upgrade state and losing everything written after it. 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 supported component versions](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9#third-party-supported-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 | | **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) | The **AI Platform** is also new on 5.9.x. If your deployment uses AI features, refer to the [AI Platform setup](/5.9/setup-guides/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 supported component versions table before scheduling the upgrade window. *** ## Rollback considerations **Plan the 5.1.x → 5.9.x upgrade as a one-way move.** There is no downgrade path from 5.9.x back to 5.1.x: no reverse migration, no configuration switch, no partial revert. The only way back is a **full point-in-time restore of every FlowX datastore** — all Postgres databases, all MongoDB databases, the Keycloak realms, and SpiceDB — to the backups taken before the upgrade window opened. Everything written after that point is discarded with the restore: process instances, tasks, documents, audit records, and every user, group, and role change. The upgrade migrates identity, configuration, and runtime data in place across systems that reference each other, which is what rules out a partial rollback. Restoring one of them while the rest stay on 5.9.x leaves the platform inconsistent rather than recovered. ### What the upgrade changes for good Most of what makes the upgrade one-way sits in these areas: * **Identity.** Keycloak realms and every service account are reorganized during the upgrade. Going back means returning to the realm export taken beforehand, and with it losing the end users onboarded, passwords reset, and MFA enrolled since cutover. * **Platform data.** The database migrations are forward-only, and process instances are migrated in place. Runtime work that advanced on 5.9.x has no 5.1.x equivalent to return to. * **Access model.** End-user groups, solution sharing, and UI Flow permissions become FlowX-managed records with no 5.1.x counterpart, so the access configuration your teams rebuild after the upgrade does not survive a restore. * **AI capabilities.** Knowledge Base content is indexed into a new vector database, and the AI services it replaces leave the deployment. Returning to 5.1.x means standing the previous AI stack back up and rebuilding its indexed content. * **Client applications.** The web, iOS, and Android renderers move to a new SDK line, and custom integrations adopt a changed API surface. Reverting the platform means reverting those releases too — for mobile apps, on app-store review timelines. Individual settings that changed shape can be reverted on their own, and each topic page notes where that applies. None of them add up to a way back to 5.1.x. ### Plan the window around this Because rollback costs data, the mitigations all sit before and during the upgrade rather than after it. Restore a recent production backup into an isolated environment and run the complete upgrade against it, including the restore procedure itself. The rehearsal is where you find out whether your backups are actually restorable. Stop runtime traffic before the backups so the restore point sits as close as possible to the cutover. Every minute of traffic accepted after the backup is data a rollback would discard. Everything up to and including the data-sync job is platform work on already-migrated data. Once users log in and runtime traffic resumes, new business data accumulates on 5.9.x and the cost of restoring climbs with every hour. Make the abort decision at that boundary — see [the data-sync step](./organization-deployment#liquibase-migration) for what has to complete before anyone logs in. Confirm before the window who accepts the loss of post-cutover runtime data if a restore is called, and how long the platform may stay unavailable while it runs. This applies to crossing the LTS boundary. Moving between patch releases inside the 5.9.x family (5.9.1 to 5.9.2, for example) is a routine in-family upgrade covered by the LTS compatibility guarantee, and carries none of the migrations above. *** ## Next Start with this. It is the largest single break. Project-scoped roles, end-user groups, per-environment sharing. ## Related topics - [Engine partitioning configuration](/5.9/migrating-from-5.1-lts/engine-partitioning.md) - [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview.md) - [Deployment guidelines v5.8.0](/release-notes/v5.x/v5.8.0-may-2026/deployment-guidelines-v5.8.md) - [Deployment guidelines v5.7.0](/release-notes/v5.x/v5.7.0-april-2026/deployment-guidelines-v5.7.md) - [Prerequisites](/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/prerequisites.md)