> ## 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 Admin setup
> Complete configuration reference for the FlowX Admin microservice, including logging, databases, Kafka, and various subsystems.
This guide provides a comprehensive reference for configuring the FlowX Admin microservice using environment variables and configuration files.
## Infrastructure Prerequisites
Before setting up the Admin microservice, ensure the following components are properly set up:
* **Database Instance**: The Admin microservice connects to the same database as the FlowX.AI Engine.
* **MongoDB**: For additional data management.
* **Redis**: For caching and transient data storage.
* **Kafka**: For audit logs, events, and messaging (if using FlowX.AI Audit functionality).
## Core configuration
### Server configuration
| Environment Variable | Description | Default Value |
| ------------------------------------------- | -------------------------------------------------- | ------------- |
| `SERVER_PORT` | Port on which the Admin service will run | `8080` |
| `SPRING_APPLICATION_NAME` | Name of the application used for service discovery | `admin` |
| `SPRING_JACKSON_SERIALIZATION_INDENTOUTPUT` | Enable indented JSON output | `true` |
## Database configuration
The Admin microservice connects to the same PostgreSQL or Oracle database as the FlowX.AI Engine for storing process definitions.
| Environment Variable | Description | Example Value |
| ---------------------------- | -------------------------------- | ---------------------------------------- |
| `SPRING_DATASOURCE_URL` | JDBC URL for database connection | `jdbc:postgresql://localhost:5432/flowx` |
| `SPRING_DATASOURCE_USERNAME` | Database username | `postgres` |
| `SPRING_DATASOURCE_PASSWORD` | Database password | `[your-secure-password]` |
You will need to make sure that the user, password, connection link and database name are configured correctly, otherwise, you will receive errors at start time.
The database schema is managed by a [Liquibase](https://www.liquibase.org/) script provided with the Engine.
## MongoDB configuration
The Admin microservice also connects to a MongoDB database instance for additional data management.
| Environment Variable | Description | Example Value |
| ---------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
| `DB_USERNAME` | MongoDB username | `data-model` |
| `DB_PASSWORD` | MongoDB password | `[your-secure-password]` |
| `DB_NAME` | MongoDB database name | `data-model` |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@localhost:27017/${DB_NAME}?retryWrites=true` |
| `SPRING_DATA_MONGODB_UUIDREPRESENTATION` | UUID representation format | `standard` |
| `SPRING_DATA_MONGODB_STORAGE` | Storage type (Azure environments) | `mongodb` or `cosmosdb` |
| `MONGOCK_CHANGELOGSSCANPACKAGE_0_` | Mongock changelog scan package | `ai.flowx.admin.data.model.config.mongock` |
| `MONGOCK_TRANSACTIONENABLED` | Enable transactions for Mongock operations | `false` |
Ensure that the MongoDB configuration is compatible with the same database requirements as the FlowX.AI Engine, especially if sharing database instances.
## Redis and caching configuration
Redis is used for caching and storing transient data.
| Environment Variable | Description | Default 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 server password | `[your-secure-password]` | **Recommended** |
| `SPRING_REDIS_HOST` | Redis server hostname | `localhost` | **Deprecated** |
| `SPRING_REDIS_PORT` | Redis server port | `6379` | **Deprecated** |
| `SPRING_REDIS_PASSWORD` | Redis server password | `defaultpassword` | **Deprecated** |
| `SPRING_REDIS_TTL` | Default Redis TTL in milliseconds | `5000000` | Used in other settings |
The `SPRING_REDIS_*` variables are deprecated and will be removed in a future FlowX version. Please use the corresponding `SPRING_DATA_REDIS_*` variables instead.
## Kafka configuration
The Admin microservice uses Kafka for sending audit logs, managing scheduled timer events, platform component versions, and start timer event updates.
### General Kafka settings
| Environment Variable | Description | Default Value |
| -------------------------------- | ----------------------------- | ----------------- |
| `SPRING_KAFKA_BOOTSTRAPSERVERS` | Kafka broker addresses | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol | `PLAINTEXT` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size in bytes | `52428800` (50MB) |
### Kafka producer configuration
| Environment Variable | Description | Default Value |
| --------------------------------------- | ---------------------- | ------------------------------------------------------------- |
| `SPRING_KAFKA_PRODUCER_KEYSERIALIZER` | Key serializer class | `org.apache.kafka.common.serialization.StringSerializer` |
| `SPRING_KAFKA_PRODUCER_VALUESERIALIZER` | Value serializer class | `org.springframework.kafka.support.serializer.JsonSerializer` |
| `SPRING_KAFKA_PRODUCER_MAXREQUESTSIZE` | Maximum request size | `52428800` (50MB) |
### Kafka consumer configuration
| Environment Variable | Description | Default Value |
| -------------------------------------------- | ------------------------------------------ | -------------------------------- |
| `KAFKA_CONSUMER_GROUPID_GENERICPROCESSING` | Generic processing consumer group | `genericProcessingGroup` |
| `KAFKA_CONSUMER_THREADS_GENERICPROCESSING` | Generic processing threads | `6` |
| `KAFKA_CONSUMER_GROUPID_CONTENTTRANSLATE` | Content translation consumer group | `cms-consumer-preview` |
| `KAFKA_CONSUMER_GROUPID_RESUSAGEVALIDATION` | Resource usage validation consumer group | `cms-res-usage-validation-group` |
| `KAFKA_CONSUMER_THREADS_CONTENTTRANSLATE` | Content translation consumer threads | `1` |
| `KAFKA_CONSUMER_THREADS_RESUSAGEVALIDATION` | Resource usage validation consumer threads | `2` |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Auth exception retry interval (seconds) | `10` |
| `SPRING_KAFKA_AUTH_EXCEPTION_RETRY_INTERVAL` | Auth exception retry interval (seconds) | `10` |
### Topic naming configuration
| Environment Variable | Description | Default Value |
| -------------------------------- | ------------------------------------ | ---------------------------------------------------------------- |
| `DOT` | Reference to the primary separator | `${kafka.topic.naming.separator}` |
| `DASH` | Reference to the secondary separator | `${kafka.topic.naming.separator2}` |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Base package name | `ai${dot}flowx${dot}` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment name | `dev${dot}` |
| `KAFKA_TOPIC_NAMING_VERSION` | Topic version | `${dot}v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator | `-` |
| `KAFKA_TOPIC_NAMING_PREFIX` | Combined prefix | `${kafka.topic.naming.package}${kafka.topic.naming.environment}` |
| `KAFKA_TOPIC_NAMING_SUFFIX` | Combined suffix | `${kafka.topic.naming.version}` |
### Kafka topics configuration
#### Audit topics
| Environment Variable | Description | Pattern | Example Value |
| ----------------------- | ------------------ | ------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| `KAFKA_TOPIC_AUDIT_OUT` | Audit output topic | `${kafka.topic.naming.prefix}core${dot}trigger${dot}save${dot}audit${kafka.topic.naming.suffix}` | `ai.flowx.dev.core.trigger.save.audit.v1` |
#### Platform Topics
| Environment Variable | Description | Pattern | Example Value |
| -------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `KAFKA_TOPIC_PLATFORM_COMPONENTSVERSIONS_IN` | Components versions caching topic | `${kafka.topic.naming.prefix}core${dot}trigger${dot}platform${dot}versions${dot}caching${kafka.topic.naming.suffix}` | `ai.flowx.dev.core.trigger.platform.versions.caching.v1` |
#### Events gateway topics
| Environment Variable | Description | Pattern | Example Value |
| --------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Commands message output topic | `${kafka.topic.naming.prefix}eventsgateway${dot}process${dot}commands${dot}message${kafka.topic.naming.suffix}` | `ai.flowx.dev.eventsgateway.process.commands.message.v1` |
#### Build topics
| Environment Variable | Description | Pattern | Example Value |
| ------------------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| `KAFKA_TOPIC_BUILD_STARTTIMEREVENTS_OUT_UPDATES` | Start timer events updates topic | `${kafka.topic.naming.prefix}build${dot}start${dash}timer${dash}events${dot}updates${dot}in${kafka.topic.naming.suffix}` | `ai.flowx.dev.build.start-timer-events.updates.in.v1` |
#### Resource topics
| Environment Variable | Description | Pattern | Example Value |
| ----------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `KAFKA_TOPIC_RESOURCESUSAGES_REFRESH` | Resources usages refresh topic | `${kafka.topic.naming.prefix}application${dash}version${dot}resources${dash}usages${dot}refresh${kafka.topic.naming.suffix}` | `ai.flowx.dev.application-version.resources-usages.refresh.v1` |
| `KAFKA_TOPIC_REQUEST_CONTENT_IN` | Topic for content retrieval requests | `${kafka.topic.naming.prefix}plugin${dot}cms${dot}trigger${dot}retrieve${dot}content${kafka.topic.naming.suffix}` | `ai.flowx.dev.plugin.cms.trigger.retrieve.content.v1` |
| `KAFKA_TOPIC_REQUEST_CONTENT_OUT` | Topic for content retrieval results | `${kafka.topic.naming.prefix}${kafka.topic.naming.engineReceivePattern}plugin${dot}cms${dot}retrieve${dot}content${dot}results${kafka.topic.naming.suffix}` | `ai.flowx.dev.engine.receive.plugin.cms.retrieve.content.results.v1` |
| `KAFKA_TOPIC_APPLICATION_IN_RESUSAGEVALIDATION` | Topic for resource usage validation | `${kafka.topic.naming.prefix}application${dash}version${dot}resources${dash}usages${dot}sub${dash}res${dash}validation${dot}cms${kafka.topic.naming.suffix}` | `ai.flowx.dev.application-version.resources-usages.sub-res-validation.cms.v1` |
### OAuth authentication for Kafka
When using the `kafka-auth` profile, the following variables configure OAuth for Kafka:
| Environment Variable | Description | Default Value |
| -------------------------------- | ------------------------ | ---------------------- |
| `KAFKA_OAUTH_CLIENTID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENTSECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint URI | `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`.
## Logging configuration
The FlowX Admin microservice provides granular control over logging levels for different components:
| Environment Variable | Description | Default Value | |
| -------------------- | ------------------------------------------- | ------------- | - |
| `LOGGING_LEVEL_ROOT` | Log level for root Spring Boot microservice | `INFO` | |
| `LOGGING_LEVEL_APP` | Log level for application-specific code | `DEBUG` | |
## Localization settings
| Environment Variable | Description | Default Value |
| ------------------------------ | ---------------------------------- | ------------- |
| `APPLICATION_DEFAULTLOCALE` | Default locale for the application | `en` |
| `APPLICATION_SUPPORTEDLOCALES` | List of supported locales | `en, ro` |
## Health monitoring
| Environment Variable | Description | Default Value |
| ---------------------------------------------- | ---------------------------------------- | --------------------------------------- |
| `MANAGEMENT_HEALTH_DB_ENABLED` | Enable database health checks | `true` |
| `MANAGEMENT_HEALTH_KAFKA_ENABLED` | Enable Kafka health checks | `true` |
| `MANAGEMENT_SERVER_ADDRESS` | Management server bind address | `0.0.0.0` |
| `MANAGEMENT_SERVER_PORT` | Management server port | `8081` |
| `MANAGEMENT_SERVER_BASEPATH` | Base path for management endpoints | `/manage` |
| `MANAGEMENT_SECURITY_ENABLED` | Enable security for management endpoints | `false` |
| `MANAGEMENT_ENDPOINTS_WEB_BASEPATH` | Base path for actuator endpoints | `/actuator` |
| `MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE` | Endpoints to expose | `health,info,metrics,metric,prometheus` |
| `MANAGEMENT_ENDPOINT_HEALTH_PROBES_ENABLED` | Enable Kubernetes probes | `true` |
| `MANAGEMENT_ENDPOINT_HEALTH_SHOWDETAILS` | Show health check details | `always` |
| `MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED` | Enable Prometheus metrics export | `false` |
### Platform health configuration
| Environment Variable | Description | Default Value |
| ----------------------------------------- | --------------------------------------------- | --------------------------------------- |
| `FLOWX_PLATFORMHEALTH_NAMESPACE` | Kubernetes namespace for health checks | `flowx` |
| `FLOWX_PLATFORMHEALTH_MANAGEMENTBASEPATH` | Base path for management endpoints | `${management.server.base-path}` |
| `FLOWX_PLATFORMHEALTH_ACTUATORBASEPATH` | Base path for actuator endpoints | `${management.endpoints.web.base-path}` |
| `FLOWX_PLATFORMHEALTH_ANNOTATIONNAME` | Kubernetes annotation name for health checks | `flowx.ai/health` |
| `FLOWX_PLATFORMHEALTH_ANNOTATIONVALUE` | Kubernetes annotation value for health checks | `true` |
## Multi-edit and undo/redo configuration
| Environment Variable | Description | Default Value |
| --------------------------------------- | ----------------------------------------------- | ------------- |
| `FLOWX_MULTIEDIT_TTL` | Time-to-live for multi-edit sessions in seconds | `45` |
| `FLOWX_UNDOREDO_TTL` | Time-to-live for undo/redo actions in seconds | `86400` |
| `FLOWX_UNDOREDO_CLEANUP_CRONEXPRESSION` | Cron expression for undo/redo cleanup | `0 0 2 ?` |
| `FLOWX_UNDOREDO_CLEANUP_DAYS` | Days to keep deleted undo/redo items | `2` |
## Resources usage configuration
| Environment Variable | Description | Default Value |
| ------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------- |
| `FLOWX_LIB_RESOURCESUSAGES_ENABLED` | Enable resources usage tracking | `true` |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_ENABLED` | Enable listener for resource usage refreshes | `true` |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_THREADCOUNT` | Thread count for resource usage collector | `5` |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_MAXBATCHSIZE` | Maximum batch size for resource usage collection | `1000` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_GROUPID_RESOURCESUSAGESREFRESH` | Consumer group ID for resource usage refresh | `adminResourcesUsagesRefreshGroup` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_THREADS_RESOURCESUSAGESREFRESH` | Number of consumer threads for resource usage refresh | `3` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_TOPIC_RESOURCE_USAGES_REFRESH` | Kafka topic for resource usage refresh | `${kafka.topic.resources-usages.refresh}` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval in seconds after auth exceptions | `3` |
## Authentication and Authorization Configuration
The FlowX Admin microservice supports authentication and authorization through OpenID Connect (with Keycloak as the default provider) and allows detailed role-based access control.
### OpenID Connect Configuration
| Environment Variable | Description | Default Value |
| ------------------------------------- | ----------------------------- | ------------- |
| `SECURITY_TYPE` | Security type | `oauth2` |
| `SECURITY_OAUTH2CLIENT` | Enable OAuth2 client | `enabled` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the OAuth2 server | |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | |
| `SECURITY_OAUTH2_CLIENT_CLIENTID` | OAuth2 client ID | |
| `SECURITY_OAUTH2_CLIENT_CLIENTSECRET` | OAuth2 client secret | |
### Service Account Configuration
The following service account configuration is deprecated but still supported for backward compatibility.
| Environment Variable | Description | Default Value |
| ---------------------------------------------------- | ----------------------------- | ------------------------------------- |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENTID` | Service account client ID | `flowx-${SPRING_APPLICATION_NAME}-sa` |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENTSECRET` | Service account client secret | `client-secret` |
### Spring Security OAuth2 Client Configuration
| Environment Variable | Description | Default Value |
| -------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_INTROSPECTIONURI` | Token introspection URI | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_REALM}/protocol/openid-connect/token/introspect` |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_CLIENTID` | Resource server client ID | `${SECURITY_OAUTH2_CLIENT_CLIENTID}` |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_CLIENTSECRET` | Resource server client secret | `${SECURITY_OAUTH2_CLIENT_CLIENTSECRET}` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_PROVIDER` | Identity provider name | `mainAuthProvider` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTNAME` | Client name | `mainIdentity` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Client ID | `${SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTID}` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Client secret | `${SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTSECRET}` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_AUTHORIZATIONGRANTTYPE` | Authorization grant type | `client_credentials` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_AUTHENTICATION_METHOD` | Client authentication method | `client_secret_post` |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_REALM}/protocol/openid-connect/token` |
### Identity Provider Configuration
| Environment Variable | Description | Default Value |
| ----------------------------- | ------------------------------------ | ------------------------------------------------- |
| `OPENID_PROVIDER` | OpenID provider type | `keycloak` (possible values: `keycloak`, `entra`) |
| `FLOWX_AUTHENTICATE_CLIENTID` | Client ID for authentication service | `flowx-platform-authenticate` |
| `FLOWX_PROCESS_DEFAULTROLES` | Default roles for processes | `FLOWX_ROLE` |
#### Keycloak Configuration
| Environment Variable | Description | Default Value |
| -------------------------------------- | ---------------------- | ------------------------------------------------------- |
| `OPENID_KEYCLOAK_BASE_SERVER_URL` | Keycloak server URL | `${SECURITY_OAUTH2_BASESERVERURL}` |
| `OPENID_KEYCLOAK_REALM` | Keycloak realm | `${SECURITY_OAUTH2_REALM}` |
| `OPENID_KEYCLOAK_CLIENT_CLIENT_ID` | Keycloak client ID | `${SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENTID}` |
| `OPENID_KEYCLOAK_CLIENT_CLIENT_SECRET` | Keycloak client secret | `${SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENTSECRET}` |
#### Microsoft Entra ID configuration
| Environment Variable | Description | Default Value |
| ---------------------------- | ----------------------------- | ------------------------------------------------------------------------- |
| `OPENID_ENTRA_GRAPH_SCOPE` | Microsoft Graph API scope | `https://graph.microsoft.com/.default` |
| `OPENID_ENTRA_TENANT_ID` | Microsoft Entra tenant ID | |
| `OPENID_ENTRA_CLIENT_ID` | Microsoft Entra client ID | `${SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID}` |
| `OPENID_ENTRA_CLIENT_SECRET` | Microsoft Entra client secret | `${SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET}` |
| `OPENID_ENTRA_PRINCIPAL_ID` | Microsoft Entra principal ID | |
The role-based access control is configured in the application YAML and grants specific permissions for platform management, user management, process management, integrations management, and configuration management.
In production environments, never use the default service account credentials. Always configure secure, environment-specific credentials for authentication.
Sensitive information such as passwords and client secrets should be managed securely using environment variables or a secrets management solution in production environments.