Skip to main content
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

​
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

Connect the CMS to an OAuth 2.0 identity management platform by setting the following variables:
Environment variableDescriptionDefault Value
SECURITY_TYPESecurity typeoauth2
SECURITY_OAUTH2_BASESERVERURLBase URL for the OAuth 2.0 Authorization Server
SECURITY_OAUTH2_REALMOAuth2 realm name
SECURITY_OAUTH2_CLIENT_CLIENT_IDClient ID for token introspection
SECURITY_OAUTH2_CLIENT_CLIENT_SECRETClient secret for token introspection

​
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 variableDescriptionDefault value
APPLICATION_FLOWXRUNTIMESANAMEName of the Runtime Manager service account in Keycloakflowx-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 variableDescriptionDefault value
SPRING_DATA_MONGODB_URIURI for connecting to the CMS MongoDB instanceFormat: mongodb://${DB_USERNAME}:${DB_PASSWORD}@<host1>,<host2>,<arbiter-host>:<port>/${DB_NAME}?retryWrites=false
DB_USERNAMEMongoDB usernamecms-core
DB_NAMEMongoDB database namecms-core
DB_PASSWORDMongoDB password
MONGOCK_TRANSACTIONENABLEDEnables transactions in MongoDB for Mongock libraryfalse (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:
Environment variableDescriptionDefault value
SPRING_DATA_MONGODB_RUNTIME_URIURI for connecting to Runtime MongoDBFormat: mongodb://${RUNTIME_DB_USERNAME}:${RUNTIME_DB_PASSWORD}@<host1>,<host2>,<arbiter-host>:<port>/${RUNTIME_DB_NAME}?retryWrites=false
RUNTIME_DB_USERNAMERuntime MongoDB usernameapp-runtime
RUNTIME_DB_NAMERuntime MongoDB database nameapp-runtime
RUNTIME_DB_PASSWORDRuntime MongoDB password
SPRING_DATA_MONGODB_STORAGEStorage 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 VariableDescriptionExample ValueStatus
SPRING_DATA_REDIS_HOSTRedis server hostnamelocalhostRecommended
SPRING_DATA_REDIS_PORTRedis server port6379Recommended
SPRING_DATA_REDIS_PASSWORDRedis authentication password-Recommended
REDIS_TTLCache TTL in milliseconds5000000Optional
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 variableDescriptionDefault value
SPRING_KAFKA_BOOTSTRAPSERVERSAddress of the Kafka serverlocalhost:9092
SPRING_KAFKA_SECURITY_PROTOCOLSecurity protocol for Kafka"PLAINTEXT"

​
Auth and retry configuration

Environment variableDescriptionDefault value
KAFKA_AUTHEXCEPTIONRETRYINTERVALRetry interval after an authorization exception10
KAFKA_MESSAGE_MAX_BYTESMaximum message size in bytes52428800 (50MB)

​
Consumer group configuration

Environment variableDescriptionDefault value
KAFKA_CONSUMER_GROUPID_CONTENTTRANSLATEGroup ID for content translationcms-consumer-group
KAFKA_CONSUMER_GROUPID_RESUSAGEVALIDATIONGroup ID for resource usage validationcms-res-usage-validation-group

​
Consumer thread configuration

Environment variableDescriptionDefault value
KAFKA_CONSUMER_THREADS_CONTENTTRANSLATEThreads for content translation1
KAFKA_CONSUMER_THREADS_RESUSAGEVALIDATIONThreads for resource usage validation2

​
Topic naming configuration

Environment VariableDescriptionDefault Value
KAFKA_TOPIC_NAMING_PACKAGEPackage prefix for topic namesai.flowx.
KAFKA_TOPIC_NAMING_ENVIRONMENTEnvironment segment for topic names
KAFKA_TOPIC_NAMING_VERSIONVersion suffix for topic names.v1
KAFKA_TOPIC_NAMING_SEPARATORPrimary separator for topic names.
KAFKA_TOPIC_NAMING_SEPARATOR2Secondary separator for topic names-
KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERNEngine receive patternengine.receive.

​
Content request topics

Environment variableDescriptionDefault value
KAFKA_TOPIC_REQUEST_CONTENT_INTopic for incoming content retrieval requestsai.flowx.plugin.cms.trigger.retrieve.content.v1
KAFKA_TOPIC_REQUEST_CONTENT_OUTTopic for content retrieval resultsai.flowx.engine.receive.plugin.cms.retrieve.content.results.v1

​
Audit topics

Environment variableDescriptionDefault value
KAFKA_TOPIC_AUDIT_OUTTopic for sending audit logsai.flowx.core.trigger.save.audit.v1

​
Application resource usage validation

Environment variableDescriptionDefault value
KAFKA_TOPIC_APPLICATION_IN_RESUSAGEVALIDATIONTopic for resource usage validationai.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:
  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
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 VariableDescriptionDefault Value
KAFKA_OAUTH_CLIENT_IDOAuth client IDkafka
KAFKA_OAUTH_CLIENT_SECRETOAuth client secretkafka-secret
KAFKA_OAUTH_TOKEN_ENDPOINT_URIOAuth token endpointkafka.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 VariableDescriptionDefault Value
FLOWX_SPICEDB_HOSTSpiceDB server hostnamespicedb
FLOWX_SPICEDB_PORTSpiceDB server port50051
FLOWX_SPICEDB_TOKENSpiceDB authentication token-

​
Configuring logging

Environment variableDescription
LOGGING_LEVEL_ROOTLog level for root service logs
LOGGING_LEVEL_APPLog level for application-specific logs

​
Configuring file storage

​
Public storage

Environment variableDescription
APPLICATION_FILESTORAGE_S3_SERVERURLURL of S3 server for file storage
APPLICATION_FILESTORAGE_S3_BUCKETNAMES3 bucket name
APPLICATION_FILESTORAGE_S3_ROOTDIRECTORYRoot directory in S3 bucket
APPLICATION_FILESTORAGE_S3_CREATEBUCKETAuto-create bucket if it doesn’t exist (true/false)
APPLICATION_FILESTORAGE_S3_PUBLICURLPublic 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 variableDescription
APPLICATION_FILESTORAGE_S3_PRIVATESERVERURLURL of S3 server for private storage
APPLICATION_FILESTORAGE_S3_PRIVATEBUCKETNAMES3 bucket name for private storage
APPLICATION_FILESTORAGE_S3_PRIVATECREATEBUCKETAuto-create private bucket (true/false)
APPLICATION_FILESTORAGE_S3_PRIVATEACCESSKEYAccess key for private S3 server
APPLICATION_FILESTORAGE_S3_PRIVATESECRETKEYSecret key for private S3 server

​
Configuring file upload size

Environment variableDescriptionDefault value
SPRING_SERVLET_MULTIPART_MAXFILESIZEMaximum file size for uploads50MB
SPRING_SERVLET_MULTIPART_MAXREQUESTSIZEMaximum request size for uploads50MB
Setting high file size limits may increase vulnerability to potential attacks. Consider security implications before increasing these limits.

​
Configuring application management

​
Troubleshooting

​
Common issues

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

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
Last modified on March 25, 2026