FlowX CMS setup

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

MongoDB
Redis
Kafka
Elasticsearch

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

Dependencies overview

MongoDB instance
Authorization & access roles
Redis
Kafka

Configuration

Set application defaults

Define the default application name for retrieving content:

application:
    defaultApplication: ${DEFAULT_APPLICATION:flowx}

If this configuration is not provided, the default value will be set to flowx.

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`

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 for the full list.

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`

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.

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. The database name (`cms-core`) is fixed in the URI path; only the credentials are parameterized.	Format: `mongodb://${DB_USERNAME}:${DB_PASSWORD}@<host1>,<host2>,<arbiter-host>:<port>/cms-core?retryWrites=false`
`DB_USERNAME`	MongoDB username (shared by the CMS and runtime connections)	`paperflow`
`DB_PASSWORD`	MongoDB password (shared by the CMS and runtime connections)	`password`
`MONGOCK_TRANSACTIONENABLED`	Enables transactions in MongoDB for Mongock library	`false` (Set to `false` to support successful migrations)

Set MONGOCK_TRANSACTIONENABLED to false due to known issues with transactions in MongoDB version 5.

Configuring MongoDB (runtime database - additional data)

CMS also connects to a Runtime MongoDB instance for operational data. It reuses the same DB_USERNAME and DB_PASSWORD as the primary connection — there are no separate runtime credential variables:

Environment variable	Description	Default value
`SPRING_DATA_MONGODB_RUNTIME_ENABLED`	Enable the Runtime MongoDB connection	`true`
`SPRING_DATA_MONGODB_RUNTIME_URI`	URI for connecting to Runtime MongoDB. Reuses `DB_USERNAME` / `DB_PASSWORD`; the database name (`app-runtime`) is fixed in the URI path.	Format: `mongodb://${DB_USERNAME}:${DB_PASSWORD}@<host1>,<host2>,<arbiter-host>:<port>/app-runtime?retryWrites=false`
`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

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.

For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the Redis Configuration guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

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`

All actions that match a configured pattern will be consumed by the engine.

Inter-Service topic coordination

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

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

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.

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`

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.

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.

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.

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`

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

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

Troubleshooting

Common issues

CMS service fails to start

Symptoms: Service crashes on startup or fails health checks.Solutions:

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

Enumerations not syncing

Symptoms: Enumeration values are outdated or not appearing across services.Solutions:

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

Media library uploads failing

Symptoms: File uploads return errors or files are not visible in the Media Library.Solutions:

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

Content not appearing in Designer

Symptoms: CMS content (enumerations, media files) is not visible in the FlowX Designer.Solutions:

Verify CMS service is running and healthy by checking the /actuator/health endpoint
Ensure the CMS service is reachable from the Designer — check network policies and ingress configuration
Verify CORS settings allow requests from the Designer domain
Check that the authorization configuration is correct and the Designer can authenticate with the CMS service

Enumerations

Manage taxonomies and enumeration values for your applications

Media Library

Store and manage media assets used across your applications

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes

Microservices

AI Platform

Plugins

Observability

Access management

FlowX CMS setup

Dependencies overview

Configuration

Set application defaults

Configuring authorization & access roles

Configuring Runtime Manager service account

Configuring MongoDB

Configuring MongoDB (runtime database - additional data)

Configuring Redis

Configuring Kafka

Connection settings

Auth and retry configuration

Consumer group configuration

Consumer thread configuration

Topic naming configuration

Content request topics

Audit topics

Application resource usage validation

Inter-Service topic coordination

Kafka authentication

CAS lib configuration

Configuring logging

Configuring file storage

Public storage

Private storage

Configuring file upload size

Configuring application management

Ingress and CORS

Service routes

CORS configuration

Troubleshooting

Common issues

Enumerations

Media Library

Redis Configuration

​Dependencies overview

​Configuration

​Set application defaults

​Configuring authorization & access roles

​Configuring Runtime Manager service account

​Configuring MongoDB

​Configuring MongoDB (runtime database - additional data)

​Configuring Redis

​Configuring Kafka

​Connection settings

​Auth and retry configuration

​Consumer group configuration

​Consumer thread configuration

​Topic naming configuration

​Content request topics

​Audit topics

​Application resource usage validation

​Inter-Service topic coordination

​Kafka authentication

​CAS lib configuration

​Configuring logging

​Configuring file storage

​Public storage

​Private storage

​Configuring file upload size

​Configuring application management

​Ingress and CORS

​Service routes

​CORS configuration

​Troubleshooting

​Common issues

​Related resources

Enumerations

Media Library

Redis Configuration

Dependencies overview

Configuration

Set application defaults

Configuring authorization & access roles

Configuring Runtime Manager service account

Configuring MongoDB

Configuring MongoDB (runtime database - additional data)

Configuring Redis

Configuring Kafka

Connection settings

Auth and retry configuration

Consumer group configuration

Consumer thread configuration

Topic naming configuration

Content request topics

Audit topics

Application resource usage validation

Inter-Service topic coordination

Kafka authentication

CAS lib configuration

Configuring logging

Configuring file storage

Public storage

Private storage

Configuring file upload size

Configuring application management

Ingress and CORS

Service routes

CORS configuration

Troubleshooting

Common issues

Related resources