> ## 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]` |

<Warning>
  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.
</Warning>

<Info>
  The database schema is managed by a [Liquibase](https://www.liquibase.org/) script provided with the Engine.
</Info>

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

<Info>
  Ensure that the MongoDB configuration is compatible with the same database requirements as the FlowX.AI Engine, especially if sharing database instances.
</Info>

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

<Warning>
  The `SPRING_REDIS_*` variables are deprecated and will be removed in a future FlowX version. Please use the corresponding `SPRING_DATA_REDIS_*` variables instead.
</Warning>

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

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

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

<Warning>
  The following service account configuration is deprecated but still supported for backward compatibility.
</Warning>

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

<Info>
  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.
</Info>

<Warning>
  In production environments, never use the default service account credentials. Always configure secure, environment-specific credentials for authentication.
</Warning>

<Warning>
  Sensitive information such as passwords and client secrets should be managed securely using environment variables or a secrets management solution in production environments.
</Warning>


## Related topics

- [FlowX Engine setup](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup.md)
- [FlowX Advancing Controller setup](/4.7.x/setup-guides/advancing-controller-setup-guide.md)
- [FlowX.AI architecture](/4.7.x/docs/platform-overview/flowx-architecture.md)
- [FlowX Designer setup](/4.7.x/setup-guides/designer-setup-guide.md)
- [FlowX CMS setup](/4.7.x/setup-guides/cms-setup.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.