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

# FlowX CMS setup

> Set up the FlowX CMS Docker microservice for managing taxonomies and content inside an app.

Ensure the following infrastructure components are available before starting the CMS service:

* **MongoDB**
* **Redis**
* **Kafka**
* **Elasticsearch**

<Info>
  The service is pre-configured with most default values. However, some environment variables require customization during setup.
</Info>

## Dependencies overview

* [**MongoDB instance**](#mongodb-database)
* [**Authorization & access roles**](#configuring-authorization-access-roles)
* [**Redis**](#configuring-redis)
* [**Kafka**](#configuring-kafka)

***

## Configuration

### Set application defaults

Define the default application name for retrieving content:

```yaml theme={"system"}
application:
    defaultApplication: ${DEFAULT_APPLICATION:flowx}
```

<Info>
  If this configuration is not provided, the default value will be set to `flowx`.
</Info>

***

## Configuring authorization & access roles

The CMS validates incoming tokens with the JWT public key mechanism. It does not initiate service-to-service calls, so it has no service-account client registration:

| 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                                       |                                  |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |

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

***

## Configuring Runtime Manager service account

The CMS service requires access to the Runtime Manager service account for operations such as merging media file updates, managing builds, and handling application version transitions.

| Environment variable             | Description                                             | Default value              |
| -------------------------------- | ------------------------------------------------------- | -------------------------- |
| `APPLICATION_FLOWXRUNTIMESANAME` | Name of the Runtime Manager service account in Keycloak | `flowx-runtime-manager-sa` |

<Info>
  This service account is required for CMS to perform operations like merging media file updates and coordinating with the Runtime Manager service. The service account must exist in Keycloak with the appropriate roles assigned.
</Info>

***

## Configuring MongoDB

The CMS requires MongoDB for taxonomy and content storage. Configure MongoDB with the following variables:

| Environment variable         | Description                                         | Default value                                                                                                        |
| ---------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `SPRING_DATA_MONGODB_URI`    | URI for connecting to the CMS MongoDB instance      | Format: `mongodb://${DB_USERNAME}:${DB_PASSWORD}@<host1>,<host2>,<arbiter-host>:<port>/${DB_NAME}?retryWrites=false` |
| `DB_USERNAME`                | MongoDB username                                    | `cms-core`                                                                                                           |
| `DB_NAME`                    | MongoDB database name                               | `cms-core`                                                                                                           |
| `DB_PASSWORD`                | MongoDB password                                    |                                                                                                                      |
| `MONGOCK_TRANSACTIONENABLED` | Enables transactions in MongoDB for Mongock library | `false` (Set to `false` to support successful migrations)                                                            |

<Info>
  Set `MONGOCK_TRANSACTIONENABLED` to `false` due to known issues with transactions in MongoDB version 5.
</Info>

### Configuring MongoDB (runtime database - additional data)

CMS also connects to a Runtime MongoDB instance for operational data:

| Environment variable              | Description                                                | Default value                                                                                                                                |
| --------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | URI for connecting to Runtime MongoDB                      | Format: `mongodb://${RUNTIME_DB_USERNAME}:${RUNTIME_DB_PASSWORD}@<host1>,<host2>,<arbiter-host>:<port>/${RUNTIME_DB_NAME}?retryWrites=false` |
| `RUNTIME_DB_USERNAME`             | Runtime MongoDB username                                   | `app-runtime`                                                                                                                                |
| `RUNTIME_DB_NAME`                 | Runtime MongoDB database name                              | `app-runtime`                                                                                                                                |
| `RUNTIME_DB_PASSWORD`             | Runtime MongoDB password                                   |                                                                                                                                              |
| `SPRING_DATA_MONGODB_STORAGE`     | Storage type for Runtime MongoDB (Azure environments only) | `mongodb` (Options: `mongodb`, `cosmosdb`)                                                                                                   |

***

## Configuring Redis

CMS uses Redis for caching content. 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>

***

## Configuring Kafka

### Connection settings

| Environment variable             | Description                 | Default value    |
| -------------------------------- | --------------------------- | ---------------- |
| `SPRING_KAFKA_BOOTSTRAPSERVERS`  | Address of the Kafka server | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka | `"PLAINTEXT"`    |

### Auth and retry configuration

| Environment variable               | Description                                     | Default value     |
| ---------------------------------- | ----------------------------------------------- | ----------------- |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after an authorization exception | `10`              |
| `KAFKA_MESSAGE_MAX_BYTES`          | Maximum message size in bytes                   | `52428800` (50MB) |

### Consumer group configuration

| Environment variable                        | Description                            | Default value                    |
| ------------------------------------------- | -------------------------------------- | -------------------------------- |
| `KAFKA_CONSUMER_GROUPID_CONTENTTRANSLATE`   | Group ID for content translation       | `cms-consumer-group`             |
| `KAFKA_CONSUMER_GROUPID_RESUSAGEVALIDATION` | Group ID for resource usage validation | `cms-res-usage-validation-group` |

### Consumer thread configuration

| Environment variable                        | Description                           | Default value |
| ------------------------------------------- | ------------------------------------- | ------------- |
| `KAFKA_CONSUMER_THREADS_CONTENTTRANSLATE`   | Threads for content translation       | `1`           |
| `KAFKA_CONSUMER_THREADS_RESUSAGEVALIDATION` | Threads for resource usage validation | `2`           |

### Topic naming configuration

| Environment Variable                      | Description                         | Default Value     |
| ----------------------------------------- | ----------------------------------- | ----------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`              | Package prefix for topic names      | `ai.flowx.`       |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT`          | Environment segment for topic names | ` `               |
| `KAFKA_TOPIC_NAMING_VERSION`              | Version suffix for topic names      | `.v1`             |
| `KAFKA_TOPIC_NAMING_SEPARATOR`            | Primary separator for topic names   | `.`               |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`           | Secondary separator for topic names | `-`               |
| `KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN` | Engine receive pattern              | `engine.receive.` |

### Content request topics

| Environment variable              | Description                                   | Default value                                                    |
| --------------------------------- | --------------------------------------------- | ---------------------------------------------------------------- |
| `KAFKA_TOPIC_REQUEST_CONTENT_IN`  | Topic for incoming content retrieval requests | `ai.flowx.plugin.cms.trigger.retrieve.content.v1`                |
| `KAFKA_TOPIC_REQUEST_CONTENT_OUT` | Topic for content retrieval results           | `ai.flowx.engine.receive.plugin.cms.retrieve.content.results.v1` |

### Audit topics

| Environment variable    | Description                  | Default value                         |
| ----------------------- | ---------------------------- | ------------------------------------- |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

### Application resource usage validation

| Environment variable                            | Description                         | Default value                                                             |
| ----------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------- |
| `KAFKA_TOPIC_APPLICATION_IN_RESUSAGEVALIDATION` | Topic for resource usage validation | `ai.flowx.application-version.resources-usages.sub-res-validation.cms.v1` |

<Tip>
  All actions that match a configured pattern will be consumed by the engine.
</Tip>

### Inter-Service topic coordination

When configuring Kafka topics in the FlowX ecosystem, it's critical to ensure proper coordination between services:

1. **Topic name matching**: Output topics from one service must match the expected input topics of another service.

   For example:

   * `KAFKA_TOPIC_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATION_OUT_CMS` on Application Manager must match `KAFKA_TOPIC_APPLICATION_IN_RESUSAGEVALIDATION` on CMS

2. **Pattern consistency**: The pattern values must be consistent across services:

   * Process Engine listens to topics matching: `ai.flowx.engine.receive.*`
   * Integration Designer listens to topics matching: `ai.flowx.integration.receive.*`

3. **Communication flow**:
   * Other services write to topics matching the Engine's pattern → Process Engine listens
   * Process Engine writes to topics matching the Integration Designer's pattern → Integration Designer listens

<Info>
  The exact pattern value isn't critical, but it must be identical across all connected services. Some deployments require manually creating Kafka topics in advance rather than dynamically. In these cases, all topic names must be explicitly defined and coordinated.
</Info>

### Kafka authentication

For secure environments, enable OAuth authentication with the following environment variables:

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

***

## CAS lib configuration

| Environment Variable  | Description                  | Default Value |
| --------------------- | ---------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST`  | SpiceDB server hostname      | `spicedb`     |
| `FLOWX_SPICEDB_PORT`  | SpiceDB server port          | `50051`       |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `-`           |

***

## Configuring logging

| Environment variable | Description                             |
| -------------------- | --------------------------------------- |
| `LOGGING_LEVEL_ROOT` | Log level for root service logs         |
| `LOGGING_LEVEL_APP`  | Log level for application-specific logs |

***

## Configuring file storage

### Public storage

| Environment variable                       | Description                                             |
| ------------------------------------------ | ------------------------------------------------------- |
| `APPLICATION_FILESTORAGE_S3_SERVERURL`     | URL of S3 server for file storage                       |
| `APPLICATION_FILESTORAGE_S3_BUCKETNAME`    | S3 bucket name                                          |
| `APPLICATION_FILESTORAGE_S3_ROOTDIRECTORY` | Root directory in S3 bucket                             |
| `APPLICATION_FILESTORAGE_S3_CREATEBUCKET`  | Auto-create bucket if it doesn't exist (`true`/`false`) |
| `APPLICATION_FILESTORAGE_S3_PUBLICURL`     | Public URL for accessing files                          |

#### Private storage

Private CMS securely stores uploaded documents and AI-generated documents, ensuring they are accessible only via authenticated endpoints.

<Info>
  Private CMS ensures secure file storage by keeping documents hidden from the Media Library and accessible only through authenticated endpoints with access token permissions. Files can be retrieved using tags (e.g., ai\_document, ref:UUID\_doc) and are excluded from application builds.
</Info>

| Environment variable                             | Description                                 |
| ------------------------------------------------ | ------------------------------------------- |
| `APPLICATION_FILESTORAGE_S3_PRIVATESERVERURL`    | URL of S3 server for private storage        |
| `APPLICATION_FILESTORAGE_S3_PRIVATEBUCKETNAME`   | S3 bucket name for private storage          |
| `APPLICATION_FILESTORAGE_S3_PRIVATECREATEBUCKET` | Auto-create private bucket (`true`/`false`) |
| `APPLICATION_FILESTORAGE_S3_PRIVATEACCESSKEY`    | Access key for private S3 server            |
| `APPLICATION_FILESTORAGE_S3_PRIVATESECRETKEY`    | Secret key for private S3 server            |

***

## Configuring file upload size

| Environment variable                      | Description                      | Default value |
| ----------------------------------------- | -------------------------------- | ------------- |
| `SPRING_SERVLET_MULTIPART_MAXFILESIZE`    | Maximum file size for uploads    | `50MB`        |
| `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE` | Maximum request size for uploads | `50MB`        |

<Warning>
  Setting high file size limits may increase vulnerability to potential attacks. Consider security implications before increasing these limits.
</Warning>

***

## Configuring application management

***

## Ingress and CORS

The CMS Core service 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 |
| ---------- | ------------- | ---------------- |
| admin      | `/cms`        | `/`              |
| public     | `/cms`        | `/`              |

Paths are set through `services.cms-core.ingress.admin.path` / `services.cms-core.ingress.public.path` (or the corresponding `gateway.<key>.paths`) in the chart values.

### CORS configuration

| Environment Variable            | Description                                                                                                                                                                                        | Default Value |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOW_ORIGIN` | 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 CMS. | `-`           |

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](./ingress-configuration).

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="CMS service fails to start">
    **Symptoms:** Service crashes on startup or fails health checks.

    **Solutions:**

    1. Verify MongoDB connection URI is correct and the `cms-core` database is accessible
    2. Check that Kafka bootstrap servers are reachable and topic names are properly configured
    3. Ensure Redis is running and connection parameters are correct
    4. Review startup logs for specific error messages related to database migrations (`MONGOCK_TRANSACTIONENABLED` should be `false`)
  </Accordion>

  <Accordion title="Enumerations not syncing">
    **Symptoms:** Enumeration values are outdated or not appearing across services.

    **Solutions:**

    1. Verify Kafka topics for content translation are correctly configured (`KAFKA_TOPIC_REQUEST_CONTENT_IN` and `KAFKA_TOPIC_REQUEST_CONTENT_OUT`)
    2. Check that consumer group IDs are unique and not conflicting with other service instances
    3. Ensure Redis cache is not serving stale data — restart the CMS service to force cache invalidation
    4. Confirm the resource usage validation topic (`KAFKA_TOPIC_APPLICATION_IN_RESUSAGEVALIDATION`) is properly configured
  </Accordion>

  <Accordion title="Media library uploads failing">
    **Symptoms:** File uploads return errors or files are not visible in the Media Library.

    **Solutions:**

    1. Verify S3/MinIO server URL and bucket configuration (`APPLICATION_FILESTORAGE_S3_SERVERURL`, `APPLICATION_FILESTORAGE_S3_BUCKETNAME`)
    2. Check that the bucket exists or `APPLICATION_FILESTORAGE_S3_CREATEBUCKET` is set to `true`
    3. Ensure file size limits are appropriate (`SPRING_SERVLET_MULTIPART_MAXFILESIZE` and `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE`)
    4. For private storage, verify access key and secret key credentials are correct
  </Accordion>

  <Accordion title="Content not appearing in Designer">
    **Symptoms:** CMS content (enumerations, media files) is not visible in the FlowX Designer.

    **Solutions:**

    1. Verify CMS service is running and healthy by checking the `/actuator/health` endpoint
    2. Ensure the CMS service is reachable from the Designer — check network policies and ingress configuration
    3. Verify CORS settings allow requests from the Designer domain
    4. Check that the authorization configuration is correct and the Designer can authenticate with the CMS service
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Enumerations" icon="list" href="../docs/platform-deep-dive/core-extensions/content-management/enumerations">
    Manage taxonomies and enumeration values for your applications
  </Card>

  <Card title="Media Library" icon="photo-film" href="../docs/platform-deep-dive/core-extensions/content-management/media-library">
    Store and manage media assets used across your applications
  </Card>

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