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

> [!NOTE]
>
> The [**Application Manager**](https://docs.flowx.ai/6.x/setup-guides/application-manager.md) 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.

## 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**](#kafka-configuration)
* [**Authentication & access roles**](#authentication-configuration)
* [**Logging**](https://docs.flowx.ai/6.x/setup-guides/setup-guides-overview.md#logging-configuration)

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

## Core service configuration

| Environment Variable | Description | Example Value |
| - | - | - |
| `LOGGING_CONFIG` | 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**](https://docs.flowx.ai/6.x/setup-guides/application-manager.md). 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 |

> [!NOTE]
>
> 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.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](https://docs.flowx.ai/5.1/setup-guides/redis-configuration.md) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

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

> [!NOTE]
>
> 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`.

### Kafka topics

Since the Runtime Manager shares the same container image as the [Application Manager](https://docs.flowx.ai/6.x/setup-guides/application-manager.md), 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.

#### 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_AUTHEXCEPTIONRETRYINTERVAL` | 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` |

> [!NOTE]
>
> For the full list of application resource topics (export, import, sync, resource usages, etc.), see the [Application Manager Kafka configuration](https://docs.flowx.ai/6.x/setup-guides/application-manager.md#kafka-topic-configuration).

***

## Scheduler configuration

The Runtime Manager scheduler times out stalled build import/export sessions:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SCHEDULER_BUILDTIMEOUT` | Build import/export timeout, in seconds | `14400` |
| `FLOWX_SCHEDULER_BUILDIMPEXTIMEOUTCRON` | Build import/export timeout check cron | `0 */10 * * * *` |

A build import or export that stays in progress longer than `FLOWX_SCHEDULER_BUILDTIMEOUT` is moved to `IMPORT_TIMEOUT` or `EXPORT_TIMEOUT`. The default of `14400` seconds is 4 hours. `FLOWX_SCHEDULER_BUILDIMPEXTIMEOUTCRON` controls how often the check runs, every 10 minutes by default.

> [!NOTE]
>
> Raise `FLOWX_SCHEDULER_BUILDTIMEOUT` if large builds are legitimately being marked as timed out before they finish. The equivalent timeouts for **application version** import/export are configured on the Application Manager. See [Application Manager scheduler configuration](https://docs.flowx.ai/6.x/setup-guides/application-manager.md#scheduler-configuration).

***

## Authentication configuration

### Security type

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |

### Service account configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-runtime-manager-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | *sensitive* |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](https://docs.flowx.ai/6.x/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access.md) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | *sensitive* |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!NOTE]
>
> The Runtime Manager and the Application Manager are built from the same artifact and share the `flowx-runtime-manager-sa` service account.

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](https://docs.flowx.ai/5.9/migrating-from-5.1-lts/authentication-iam.md) for the full list.

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

> [!NOTE]
>
> 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.

## Temporary storage for build exports and imports

Runtime Manager uses the container's `/tmp` directory as working space for build exports and imports. It writes each exported resource and assembles the export archive in `/tmp` before uploading it to S3-compatible storage, and it unpacks imported builds there.

Size `/tmp` to hold your largest build both unpacked and as a zip archive, for every export or import that runs at the same time. Builds exported with **Include media file content** turned on are larger.

When the container runs with a read-only root filesystem, mount a writable volume at `/tmp`. Prefer a disk-backed `emptyDir`: a memory-backed one (`medium: Memory`) counts against the container's memory limit.

To increase the volume, override the Runtime Manager volumes in your Helm values:

```yaml theme={"dark"}
services:
  runtime-manager:
    extraVolumes:
      - name: tmpdir
        emptyDir:
          sizeLimit: 2Gi
    extraVolumeMounts:
      - name: tmpdir
        mountPath: /tmp
        readOnly: false
```

If your Runtime Manager values aren't nested under `services`, set `extraVolumes` and `extraVolumeMounts` at the top level of those values instead.

> [!NOTE]
>
> `extraVolumes` and `extraVolumeMounts` are lists, so your values replace the whole list. Include any other volumes the Runtime Manager already mounts.

## Ingress and CORS

The Runtime Manager is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group | External path | Backend receives |
| - | - | - |
| public | `/rtm/api/runtime` | `/api/runtime/...` |
| admin | `/rtm/api/build-mgmt` | `/api/build-mgmt/...` |
| admin-instances | `/rtm/api/runtime`, `/rtm/api/runtime-internal` | `/api/runtime/...`, `/api/runtime-internal/...` |

All routes strip the `/rtm` prefix before forwarding to the backend. Paths are set through `services.runtime-manager.ingress.<key>.path` (or `gateway.<key>.paths`) in the chart values; the chart also applies `nginx.ingress.kubernetes.io/proxy-body-size: 50m` on the admin route by default to support larger application-version uploads. The admin-instances ingress uses a regex pattern (`/rtm/api/(runtime|runtime-internal)`) with a rewrite annotation under Ingress mode; under Gateway API mode the chart renders two separate `PathPrefix` rules instead.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls Runtime Manager. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](https://docs.flowx.ai/6.x/setup-guides/ingress-configuration.md).

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

***

## Troubleshooting

### Common issues

> [accordion] 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] 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] 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 `jwt-public-key`
> 5. Verify the Keycloak base server URL is accessible from the pod

> [accordion] Build exports fail with No space left on device
>
> **Symptoms:** Some build exports or imports fail with `No space left on device` while others succeed, and the failures look random.
>
> **Solutions:**
>
> 1. Check the size of the volume mounted at `/tmp` in the Runtime Manager pod
> 2. Increase its `sizeLimit` as described in [Temporary storage for build exports and imports](#temporary-storage-for-build-exports-and-imports)
> 3. Switch a memory-backed `emptyDir` (`medium: Memory`) to a disk-backed one
> 4. To free the space right away, replace the Runtime Manager pods, for example with `kubectl rollout restart`. An `emptyDir` volume is emptied only when its pod is removed, not when the container restarts.

***

## Related resources

> [card] [Application Manager](https://docs.flowx.ai/6.x/setup-guides/application-manager.md)
>
> Companion service sharing the same container image and Helm chart

> [card] [Redis Configuration](https://docs.flowx.ai/6.x/setup-guides/redis-configuration.md)
>
> Complete Redis setup including Sentinel and Cluster modes

> [card] [Kafka Authentication](https://docs.flowx.ai/6.x/setup-guides/kafka-authentication-config.md)
>
> Configure Kafka security and authentication

> [card] [IAM Configuration](https://docs.flowx.ai/6.x/setup-guides/access-management/configuring-an-iam-solution.md)
>
> Identity and access management setup


## Related topics

- [Microservices setup guides](https://docs.flowx.ai/6.x/setup-guides/setup-guides-overview.md)
- [Application Manager setup](https://docs.flowx.ai/6.x/setup-guides/application-manager.md)
- [Organization Manager setup](https://docs.flowx.ai/6.x/setup-guides/organization-manager-setup.md)
- [FlowX CMS setup](https://docs.flowx.ai/6.x/setup-guides/cms-setup.md)
- [Configuring an IAM solution (Keycloak)](https://docs.flowx.ai/6.x/setup-guides/access-management/configuring-an-iam-solution.md)


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