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

# Runtime manager setup

> This guide provides a step-by-step process for setting up and configuring the Runtime Manager module, including database, Kafka, and OAuth2 authentication settings to manage runtime and build configurations.

<Info>
  The [**Application Manager**](./application-manager) and **Runtime Manager** share the same container image and Helm chart. Refer to the **Deployment Guidelines** in the release notes to ensure compatibility and verify the correct version.
</Info>

## Infrastructure prerequisites

The Runtime Manager service requires the following components to be set up before it can be started:

* **PostgreSQL**
* **MongoDB**
* **Redis**
* **Kafka**
* **OAuth2 Authentication**

## Dependencies

* [**Database configuration**](#database-configuration)
* [**Kafka configuration**](#configuring-kafka)
* [**Authentication & access roles**](#configuring-authentication-and-access-roles)
* [**Logging**](./setup-guides-overview#logging)

## Change the application name

| Environment Variable      | Description                                               | Example Value     |
| ------------------------- | --------------------------------------------------------- | ----------------- |
| `SPRING_APPLICATION_NAME` | Service identifier used for service discovery and logging | `runtime-manager` |

<Warning>
  Default Value: `application-manager -> must be changed to `runtime-manager
</Warning>

## Core service configuration

| Environment Variable         | Description                                                                                                                                                                                                                                                                          | Example Value        |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
| `FLOWX_ENVIRONMENT_NAME`     | Environment identifier (dev, staging, prod, etc.). *Deprecated in 5.7.0*: kept for backward compatibility; the value is no longer surfaced in the Designer's Configure Environment Info page (removed) and is replaced by the environment name set during organization provisioning. | `pr`                 |
| `LOGGING_CONFIG_FILE`        | Path to logging configuration file                                                                                                                                                                                                                                                   | `logback-spring.xml` |
| `MULTIPART_MAX_FILE_SIZE`    | Maximum file size for uploads                                                                                                                                                                                                                                                        | `25MB`               |
| `MULTIPART_MAX_REQUEST_SIZE` | Maximum total request size                                                                                                                                                                                                                                                           | `25MB`               |

## Database configuration

The Runtime Manager uses the same PostgreSQL (to store application data) and MongoDB (to manage runtime data) as [**application-manager**](application-manager). Configure these database connections with the following environment variables:

### PostgreSQL (Application data)

| Environment Variable         | Description                        | Example Value                                   |
| ---------------------------- | ---------------------------------- | ----------------------------------------------- |
| `SPRING_DATASOURCE_URL`      | JDBC URL for PostgreSQL connection | `jdbc:postgresql://postgresql:5432/app_manager` |
| `SPRING_DATASOURCE_USERNAME` | PostgreSQL username                | `flowx`                                         |
| `SPRING_DATASOURCE_PASSWORD` | PostgreSQL password                | *sensitive*                                     |

### MongoDB (Runtime data)

| Environment Variable      | Description                | Example Value                                                                                                                                                         |
| ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SPRING_DATA_MONGODB_URI` | URI for MongoDB connection | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-headless:27017/${DB_NAME}?retryWrites=false` |
| `DB_NAME`                 | MongoDB database name      | `app-runtime`                                                                                                                                                         |
| `DB_USERNAME`             | MongoDB username           | `app-runtime`                                                                                                                                                         |
| `DB_PASSWORD`             | MongoDB password           | *sensitive*                                                                                                                                                           |

## Redis configuration

Runtime Manager uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

## Kafka configuration

### Kafka connection

| Environment Variable             | Description                         | Example Value                      |
| -------------------------------- | ----------------------------------- | ---------------------------------- |
| `SPRING_KAFKA_BOOTSTRAPSERVERS`  | Kafka broker addresses              | `kafka-flowx-kafka-bootstrap:9092` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment prefix for Kafka topics |                                    |

### Kafka OAuth authentication

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

### Kafka topics

Since the Runtime Manager shares the same container image as the [Application Manager](./application-manager), it uses the same Kafka topic definitions. However, the Runtime Manager conditionally activates a listener for the `build.runtime-data` topic (based on `spring.application.name=runtime-manager`), which is how it receives runtime data from the Admin service.

<Warning>
  The `KAFKA_TOPIC_BUILD_RUNTIMEDATA` topic must resolve to the same value in both Admin and Runtime Manager. If the `KAFKA_TOPIC_NAMING_ENVIRONMENT` prefix differs between services (common after export/import to a new environment), Admin will produce to one topic and Runtime Manager will consume from another, causing data not to be passed back to the calling process after subprocess execution.
</Warning>

#### Build topics

| Environment Variable                            | Description                                                 | Default Pattern                                   |
| ----------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------- |
| `KAFKA_TOPIC_BUILD_RUNTIMEDATA`                 | Build runtime data topic (consumed only by Runtime Manager) | `ai.flowx.build.runtime-data.v1`                  |
| `KAFKA_TOPIC_BUILD_UPDATE`                      | Build update topic                                          | `ai.flowx.build.update.v1`                        |
| `KAFKA_TOPIC_BUILD_CREATE`                      | Build create topic                                          | `ai.flowx.build.create.v1`                        |
| `KAFKA_TOPIC_BUILD_RESOURCE_EXPORT`             | Build export topic                                          | `ai.flowx.build.export.v1`                        |
| `KAFKA_TOPIC_BUILD_RESOURCE_IMPORT`             | Build import topic                                          | `ai.flowx.build.import.v1`                        |
| `KAFKA_TOPIC_BUILD_STARTTIMEREVENTS_IN_UPDATES` | Timer events updates topic                                  | `ai.flowx.build.start-timer-events.updates.in.v1` |

#### Consumer configuration

| Environment Variable                                    | Description                               | Default Value                            |
| ------------------------------------------------------- | ----------------------------------------- | ---------------------------------------- |
| `KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA`              | Build runtime data consumer group         | `build-runtime-data-group`               |
| `KAFKA_CONSUMER_GROUPID_BUILD_CREATE`                   | Build create consumer group               | `build-create-group`                     |
| `KAFKA_CONSUMER_GROUPID_BUILD_UPDATE`                   | Build update consumer group               | `build-update-group`                     |
| `KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_EXPORT`          | Build export consumer group               | `build-resource-export-group`            |
| `KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_IMPORT`          | Build import consumer group               | `build-resource-import-group`            |
| `KAFKA_CONSUMER_GROUPID_BUILD_STARTTIMEREVENTS_UPDATES` | Build timer events updates consumer group | `build-start-timer-events-updates-group` |
| `KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA`              | Build runtime data consumer threads       | `2`                                      |
| `KAFKA_CONSUMER_THREADS_BUILD_UPDATE`                   | Build update consumer threads             | `4`                                      |
| `KAFKA_AUTH_EXCEPTION_RETRY_INTERVAL`                   | Auth exception retry interval (seconds)   | `10`                                     |

#### Process topics

| Environment Variable                                | Description                     | Default Pattern                                                     |
| --------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------- |
| `KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN`              | Process start for event topic   | `ai.flowx.core.trigger.start-for-event.process.v1`                  |
| `KAFKA_TOPIC_PROCESS_STARTBYNAME_IN`                | Process start by name topic     | `ai.flowx.core.trigger.start-by-name.process.v1`                    |
| `KAFKA_TOPIC_PROCESS_STARTBYNAME_OUT`               | Process start by name out topic | `ai.flowx.engine.receive.core.trigger.start-by-name.process.out.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_SET`  | Set timer schedule topic        | `ai.flowx.core.trigger.set.timer-event-schedule.v1`                 |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_STOP` | Stop timer schedule topic       | `ai.flowx.core.trigger.stop.timer-event-schedule.v1`                |

#### Other topics

| Environment Variable                    | Description                   | Default Pattern                                  |
| --------------------------------------- | ----------------------------- | ------------------------------------------------ |
| `KAFKA_TOPIC_AUDIT_OUT`                 | Audit topic                   | `ai.flowx.core.trigger.save.audit.v1`            |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Events gateway messages topic | `ai.flowx.eventsgateway.receive.copyresource.v1` |

<Info>
  For the full list of application resource topics (export, import, sync, resource usages, etc.), see the [Application Manager Kafka configuration](./application-manager#kafka-topic-configuration).
</Info>

***

## Authentication configuration

### Security type

| Environment Variable | Description   | Default Value |
| -------------------- | ------------- | ------------- |
| `SECURITY_TYPE`      | Security type | `oauth2`      |

### Resource server (opaque-token introspection)

In 5.1.x, the Runtime Manager validates access tokens using opaque-token introspection against the identity provider's introspect endpoint.

| Environment Variable                   | Description                           | Default Value |
| -------------------------------------- | ------------------------------------- | ------------- |
| `SECURITY_OAUTH2_BASE_SERVER_URL`      | OAuth2 server base URL                |               |
| `SECURITY_OAUTH2_REALM`                | OAuth2 realm name                     |               |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID`     | Client ID for token introspection     |               |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | Client secret for token introspection |               |

The introspection URI is derived automatically: `${SECURITY_OAUTH2_BASE_SERVER_URL}/realms/${SECURITY_OAUTH2_REALM}/protocol/openid-connect/token/introspect`

### Service account configuration

| Environment Variable                                                | Description                   | Default Value                                                                                      |
| ------------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID`                   | Service account client ID     | `flowx-runtime-manager-sa`                                                                         |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET`               | Service account client secret | *sensitive*                                                                                        |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Provider token URI            | `${SECURITY_OAUTH2_BASE_SERVER_URL}/realms/${SECURITY_OAUTH2_REALM}/protocol/openid-connect/token` |

## File storage configuration

| Environment Variable                     | Description                      | Example Value       |
| ---------------------------------------- | -------------------------------- | ------------------- |
| `APPLICATION_FILE_STORAGE_S3_SERVER_URL` | S3-compatible storage server URL | `http://minio:9000` |
| `APPLICATION_FILE_STORAGE_S3_ACCESS_KEY` | S3 access key                    | *sensitive*         |
| `APPLICATION_FILE_STORAGE_S3_SECRET_KEY` | S3 secret key                    | *sensitive*         |

<Info>
  S3-compatible storage is used for storing application files, exports, and imports. The Runtime Manager supports MinIO, AWS S3, and other S3-compatible storage solutions.
</Info>

## Ingress configuration

The Runtime Manager uses the standard FlowX.AI ingress pattern with three separate ingress configurations. For complete setup instructions including the full ingress template, CORS configuration, and troubleshooting, see the [Ingress Configuration Guide](./ingress-configuration).

### Public ingress

**Service-specific values for Runtime Manager Public:**

* **Ingress name:** `runtime-manager-public`
* **Service path:** `/rtm/api/runtime(/|$)(.*)`
* **Service name:** `runtime-manager`
* **Rewrite target:** `/api/runtime/$2`
* **Fx-Workspace-Id:** Required

### Admin ingress

**Service-specific values for Runtime Manager Admin:**

* **Ingress name:** `runtime-manager-admin`
* **Service path:** `/rtm/api/build-mgmt(/|$)(.*)`
* **Service name:** `runtime-manager`
* **Rewrite target:** `/api/build-mgmt/$2`
* **Fx-Workspace-Id:** Required

### Admin instances ingress

**Service-specific values for Runtime Manager Admin Instances:**

* **Ingress name:** `runtime-manager-admin-instances`
* **Service path:** `/rtm/api/(runtime|runtime-internal)/(.*)`
* **Service name:** `runtime-manager`
* **Rewrite target:** `/api/$1/$2`
* **Fx-Workspace-Id:** Required

<Card title="Complete Ingress Configuration" href="./ingress-configuration" icon="network-wired">
  View the centralized ingress guide for the complete configuration template, annotations reference, and best practices.
</Card>

> **Note:** Replace placeholders in environment variables with the appropriate values for your environment before starting the service.

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Database connection failures">
    **Symptoms:** Service fails to start with database connection errors.

    **Solutions:**

    1. Verify the PostgreSQL database exists and is accessible
    2. Check that the database user has appropriate permissions
    3. Ensure network connectivity between the pod and PostgreSQL service
    4. Verify the JDBC URL format is correct
    5. For MongoDB, confirm the replica set is healthy and `retryWrites=false` is set in the connection URI
  </Accordion>

  <Accordion title="Kafka publishing failures">
    **Symptoms:** Messages not reaching consumers, runtime data not syncing between Admin and Runtime Manager.

    **Solutions:**

    1. Verify that `KAFKA_TOPIC_BUILD_RUNTIMEDATA` resolves to the same value in both Admin and Runtime Manager
    2. Check that `KAFKA_TOPIC_NAMING_ENVIRONMENT` is consistent across services
    3. Ensure Kafka broker addresses are correct and reachable
    4. Review consumer group IDs for conflicts with other deployments
    5. Check Kafka logs for authorization or connectivity errors
  </Accordion>

  <Accordion title="Service account authentication errors">
    **Symptoms:** 401/403 errors when communicating with other FlowX services.

    **Solutions:**

    1. Verify the Keycloak service account (`flowx-runtime-manager-sa`) is properly configured
    2. Check that client secrets match between configuration and Keycloak
    3. Ensure the service account has required roles assigned
    4. Confirm `SECURITY_TYPE` is set to `oauth2` (default for 5.1.x)
    5. Verify the OAuth2 base server URL, realm, and token introspection URI are accessible
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Application Manager" icon="grid-2" href="./application-manager">
    Companion service sharing the same container image and Helm chart
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="Kafka Authentication" icon="lock" href="./kafka-authentication-config">
    Configure Kafka security and authentication
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>
</CardGroup>


## Related topics

- [Microservices setup guides](/5.1/setup-guides/setup-guides-overview.md)
- [Application Manager setup](/5.1/setup-guides/application-manager.md)
- [Organization Manager setup](/5.1/setup-guides/organization-manager-setup.md)
- [FlowX CMS setup](/5.1/setup-guides/cms-setup.md)
- [Configuring an IAM solution (Keycloak)](/5.1/setup-guides/access-management/configuring-an-iam-solution.md)