FlowX CMS setup

The CMS service is a microservice designed for managing taxonomies and content inside an application. Delivered as a Docker image, it simplifies content editing and analysis. This guide provides step-by-step instructions for setting up the service and configuring it to suit your needs.

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

• Docker Engine
• 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

Connect the CMS to an OAuth 2.0 identity management platform by setting the following variables:

Environment variable	Description
SECURITY_OAUTH2_BASESERVERURL	Base URL for the OAuth 2.0 Authorization Server
SECURITY_OAUTH2_CLIENT_CLIENTID	Unique identifier for the client application
SECURITY_OAUTH2_CLIENT_CLIENTSECRET	Secret key to authenticate client requests
SECURITY_OAUTH2_REALM	Realm name for OAuth 2.0 provider authentication

For detailed role and access configuration, refer to:

FlowX CMS access rights

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

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

The service can use the same Redis component deployed for the engine. See Redis Configuration.

Environment variable	Description
SPRING_DATA_REDIS_HOST	Hostname or IP of the Redis server
SPRING_DATA_REDIS_PASSWORD	Authentication password for Redis
SPRING_REDIS_TTL	Maximum time-to-live for Redis cache keys (in seconds)

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

The suggested topic pattern naming convention:

topic:
  naming:
    package: "ai.flowx."
    environment: "dev."
    version: ".v1"
    prefix: ${kafka.topic.naming.package}${kafka.topic.naming.environment}
    suffix: ${kafka.topic.naming.version}
    engineReceivePattern: engine.receive.

Content request topics

Environment variable	Description	Default value
KAFKA_TOPIC_REQUEST_CONTENT_IN	Topic for incoming content retrieval requests	ai.flowx.dev.plugin.cms.trigger.retrieve.content.v1
KAFKA_TOPIC_REQUEST_CONTENT_OUT	Topic for content retrieval results	ai.flowx.dev.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.dev.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.dev.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.dev.engine.receive.*
   • Integration Designer listens to topics matching: ai.flowx.dev.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 configuration:

spring.config.activate.on-profile: kafka-auth

spring:
  kafka:
    security.protocol: "SASL_PLAINTEXT"
    properties:
      sasl:
        mechanism: "OAUTHBEARER"
        jaas.config: "org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required oauth.client.id=\"${KAFKA_OAUTH_CLIENT_ID:kafka}\" oauth.client.secret=\"${KAFKA_OAUTH_CLIENT_SECRET:kafka-secret}\"  oauth.token.endpoint.uri=\"${KAFKA_OAUTH_TOKEN_ENDPOINT_URI:kafka.auth.localhost}\" ;"
        login.callback.handler.class: io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler

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

The following configuration from versions before 4.1 will be deprecated in version 5.0:

• MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED: Enables or disables Prometheus metrics export.

Starting from version 4.1, use the following configuration. This setup is backwards compatible until version 5.0.

Environment variable	Description	Default value
MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLED	Enables Prometheus metrics export	false