> ## 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.

# Upgrade runbook (execution order)

> The end-to-end order to execute a 5.1.x → 5.9.x self-hosted upgrade — deploy, provision, data-sync, first login, verify — with links into each detailed topic.

The topic pages in this guide each cover *what* changes. This page covers *when* to do each thing. Follow the steps in order; each links into the detailed page for that step.

> [!WARNING]
>
> **The single ordering that most often breaks an upgrade:** run the **data-sync job before anyone logs in** (Step 7). Until it completes, every login — including FlowX Designer — fails with `Could not find all end-users group for this organization`. Do not skip ahead to login.

**1. Confirm the plan and gather inventory**

Agree the upgrade path with FlowX, get your Organization UUID, and request the custom migration scripts for inactive/archived process instances **before** the upgrade window. If you are arriving from 4.7.x, first land on the **latest 5.1.x patch**, not an arbitrary one. See [Prerequisites & upgrade path](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/prerequisites.md).

**2. Verify the source environment is fully functional**

Start the upgrade only from a healthy 5.1.x environment: **Designer → Platform Status** shows every service up, and the data-sync job from any previous upgrade completed successfully. Upgrading over a partially migrated environment produces data inconsistencies that surface much later. See [Start from a fully functional environment](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/prerequisites.md#start-from-a-fully-functional-environment).

**3. Set all required configuration before first boot**

These must be in place on the relevant services *before* you start 5.9.x — several services refuse to boot or fail silently otherwise:

* **Authentication & IAM** — `SECURITY_TYPE` on every service, service-account secrets, the two-realm setup. The largest break. See [Authentication & IAM migration](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/authentication-iam.md).
* **`ORGANIZATION_ID`** — on the 9 services that backfill `organization_id`. See [License and organization configuration](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/organization-deployment.md#organization_id-where-it-is-actually-required).
* **`license` service + env-info replacement vars** — `FLOWX_LICENSE_*`, `DEFAULT_ORGANIZATION_NAME`, the home URIs. See [License and organization configuration](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/organization-deployment.md).
* **Kafka, ingress/CORS, engine partitioning** — see [Kafka migration](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/kafka.md), [Ingress routing and CORS](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/ingress-routing.md), [Engine partitioning](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/engine-partitioning.md).

**4. Deploy the new and reorganized services**

Bring up the four new backend services (`email-gateway`, `organization-manager`, `webhook-gateway`, `license`) and apply the AI Platform reorganization (drop the 9 deprecated services, add the new ones). See the service list in the [overview](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/overview.md#new-services-since-5-1-x-lts).

**5. First boot — let Liquibase migrate**

On first boot against your 5.1.x databases, **active** process instances migrate automatically and `ORGANIZATION_ID` backfills run. **Inactive/archived** instances need the FlowX-provided scripts from Step 1 — do not resume runtime traffic until those have run. See [Liquibase migration](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/organization-deployment.md#liquibase-migration).

**6. Provision the organization**

Complete the first-launch **Environment Setup** wizard (or the [Manual Keycloak Configuration recipe](https://docs.flowx.ai/5.9/setup-guides/access-management/configuring-an-iam-solution.md) if the platform cannot administer Keycloak). Requires outbound HTTPS to FlowX SaaS for license validation. See [Creating the self-hosted organization](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/organization-deployment.md#creating-the-self-hosted-organization).

**7. Run the data-sync job — before any login**

Run data-sync and let it **finish**. It creates the "All end-users" runtime group that 5.1.x organizations lack. Until it completes, all logins fail (see the warning above). On `authorization-system` older than 10.97.0, also clear the cache after it completes. See [the data-sync warning](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/organization-deployment.md#liquibase-migration).

**8. First login and runtime authorization migration**

Now log in. Org-level roles become project-version-scoped and end-user groups move from Keycloak into FlowX. See [Runtime authorization migration](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/runtime-authorization.md).

**9. Verify**

Confirm Organization UUID in startup logs, **Designer → Platform Status** at 5.9.x versions, Liquibase complete on every service, license reachable, and `LLM_ENCRYPTION_MASTER_KEY` non-default. Full checklist in [Verify the configuration](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/organization-deployment.md#verify-the-configuration). Then migrate the renderer SDKs ([Android](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/android.md), [iOS](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/ios.md), [React](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/react.md), [Angular](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/angular.md)).

## Related resources

> [card] [Prerequisites & upgrade path](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/prerequisites.md)
>
> What to gather before you start.

> [card] [License and organization configuration](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/organization-deployment.md)
>
> The provisioning, data-sync, and license steps in detail.


## Related topics

- [Upgrade FlowX.AI within an LTS family without downtime](https://docs.flowx.ai/5.9/setup-guides/upgrade-within-lts-family.md)
- [Deployment guidelines v6.0.0](https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0.md)
- [Send message/receive message tasks](https://docs.flowx.ai/5.1/docs/building-blocks/node/message-send-received-task-node.md)
- [Adding an action to a node](https://docs.flowx.ai/5.1/docs/flowx-designer/managing-a-project-flow/adding-an-action-to-a-node.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.