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

# Overview

> Complete migration guide from FlowX.AI 4.7.x to 5.1.0 with prerequisites and step-by-step process

<Warning>
  You can only upgrade from version 4.7.8 (or newer) to 5.1.0. If you’re on an earlier version, upgrade to the latest LTS version first.
</Warning>

## Success factors

<Warning>
  Take care when following the steps below are mandatory and will prevent service startup if skipped:

  1. **SpiceDB and DGraph** must be installed before any FlowX.AI services

  <Info>
    DGraph is required only if you are using FlowX AI agents. If not, you can skip this step.
  </Info>

  2. **Organization admin user** must be configured before authorization-system service deployment
  3. **Service accounts** must have `SA_FLOWX` role assigned
  4. **Elasticsearch indices (data migration)** must complete before service upgrades
</Warning>

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

<Steps>
  <Step title="Prerequisites">
    ### Data migration (Elasticsearch indices)

    Migrate existing Elasticsearch data to support the new workspace-based architecture.

    ### Installing new third parties

    **New mandatory infrastructure components:**

    * **SpiceDB** - Authorization and permission management backend
    * **DGraph** - Graph-based data operations and relationships

    ### Upgrading existing third parties

    Update existing infrastructure to the new supported versions:

    * Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

    ### Organization admin user

    Configure the organization admin user before deploying the authorization-system service.

    ### Service accounts

    Assign `SA_FLOWX` role to all service accounts used by FlowX services.

    <Card title="Prerequisites" href="./prerequisites" icon="scroll">
      See the details on prerequisites for migration
    </Card>
  </Step>

  <Step title="Installing new services">
    Deploy new FlowX.AI 5.1.0 services in the correct order to ensure proper startup and dependency validation.

    **Required installation sequence:**

    1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
    2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](../../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)

    <Warning>
      **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.
    </Warning>

    <Card title="Install services" href="./install-services" icon="server">
      Step-by-step installation with validation procedures
    </Card>

    <Info>
      Installing Authorization System first allows you to validate all critical configurations before proceeding.
    </Info>
  </Step>

  <Step title="Update environment variables">
    Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

    **Configuration updates include:**

    * New Kafka topics and consumer groups
    * Updated Elasticsearch settings and index configurations
    * Enhanced security and authorization parameters
    * New service integration endpoints

    <Card title="Update environment variables" href="./environment-variables" icon="engine">
      Update environment variables for all existing FlowX.AI services
    </Card>
  </Step>

  <Step title="Install new versions for existing services">
    Upgrade all existing FlowX.AI services to version 5.1.0 after completing environment variable updates.
  </Step>

  <Step title="Container apps (Renderers SDKs)">
    <Card title="Container apps (Renderers SDKs)" href="./renderers" icon="scroll">
      See the details on container apps (Renderers SDKs)
    </Card>
  </Step>

  <Step title="Post-deployment steps">
    Perform the post deployment steps:

    * Validate data-sync migrations
    * Clear cache with endpoint
    * Remove deprecated configuration roles (optional)
    * Add users to default workspace

    ### Validate data-sync migrations

    Verify that all data synchronization processes completed successfully and perform additional system checks.

    ### Clear cache with endpoint

    **Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

    <Warning>
      **Cache Clearing**:

      * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
      * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.
    </Warning>

    ### Remove deprecated configuration roles (optional)

    Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

    ### Add users to default workspace

    **Process**:

    1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
    2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

    <Warning>
      **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.
    </Warning>

    <Card title="Post-deployment configuration" href="./configuration-and-migration" icon="scroll">
      Complete post-deployment procedures and validation
    </Card>

    <Card title="Troubleshooting" href="./troubleshooting" icon="wrench">
      Common issues and solutions for post-upgrade problems
    </Card>
  </Step>
</Steps>