Skip to main content

​
Configuration

The service comes with most of the needed configuration properties filled in, but there are several environment variables that need to be set up for your specific deployment.

​
Database configuration

The NoSQL DB Runner connects to MongoDB for data persistence. Configure the following variables:
Environment VariableDescriptionDefault Value
DB_USERNAMEMongoDB username for the servicenosql-db-runner
DB_PASSWORDMongoDB password (should be stored as secret)secret(mongodb-generic)
SPRING_DATA_MONGODB_URIComplete MongoDB connection stringmongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/nosql-db-runner
The MongoDB URI supports replica set configuration for high availability. The connection string includes multiple MongoDB instances and an arbiter for proper replica set functionality.

​
Configuring authorization & access roles

The NoSQL DB Runner validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the mainIdentity client registration) in the service-accounts realm:
Environment VariableDescriptionDefault Value
SECURITY_TYPEToken validation mechanism (JWT public key validation)jwt-public-key
SECURITY_OAUTH2_BASESERVERURLBase URL of the Keycloak server
SECURITY_OAUTH2_SAREALMService-accounts realm ID00000002-0002-4002-8002-000000000002
FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURLURL of the organization-manager service, used by the security libraryhttp://organization-manager:80
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTIDService account client IDflowx-nosql-db-runner-sa
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRETService account client secret (Keycloak-issued)
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTIDAnonymous service account client ID, used for anonymous runtime accessflowx-anonymous-sa
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRETAnonymous service account client secret
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURIProvider token URI, resolved against the service-accounts realm${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token
Upgrading from 5.1.x? Remove the legacy opaque-token env vars: SECURITY_OAUTH2_REALM, SECURITY_OAUTH2_CLIENT_CLIENTID, SECURITY_OAUTH2_CLIENT_CLIENTSECRET, and SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*. 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.

​
FlowX operations document limit

This setting allows you to configure the maximum number of documents that can be retrieved from MongoDB in a single request.
Environment VariableDescriptionDefault Value
FLOWX_RUNOPERATIONS_DOCUMENTLIMITMaximum number of documents to be processed in a single operation1000

​
External MongoDB connection caching

Environment VariableDescriptionDefault Value
FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIESMaximum number of cached external MongoDB connections100
FLOWX_MONGO_CONNECTIONS_CACHE_TTLTime-to-live for cached connections (duration format, e.g. 1d, 12h)1d
If you connect to many distinct external MongoDB instances, increase FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES to avoid frequent reconnections. Lower the TTL if your MongoDB credentials rotate frequently.

​
Oracle Database connection pooling

Environment VariableDescriptionDefault Value
FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIESMaximum cached JDBC connection pools100
FLOWX_JDBC_CONNECTIONS_CACHE_TTLTime-to-live for cached connection pools (duration format, e.g. 1d, 12h)1d
FLOWX_SQL_DEFAULTS_MAX_POOL_SIZEMaximum HikariCP pool size per Oracle data source5
FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDSJDBC connection timeout10
FLOWX_SQL_DEFAULTS_ROW_LIMITDefault row cap on SELECT responses1000
FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDSQuery execution timeout30
Increase FLOWX_SQL_DEFAULTS_ROW_LIMIT if your workflows need to read more than 1000 rows in a single query. Adjust FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS for long-running analytical queries.

​
Configuring logging

Control log levels for different components of the service:
Environment VariableDescriptionDefault Value
LOGGING_CONFIG_FILEPath to the logging configuration filelogback-spring.xml
LOGGING_LEVEL_ROOTRoot logger level for the Spring Boot serviceINFO
LOGGING_LEVEL_APPApplication-specific log levelINFO
Using DEBUG log levels in production environments may impact performance and generate large log volumes. Consider using INFO or WARN levels for production deployments.

​
Configuring application management

Configure management endpoints and monitoring capabilities:
Environment VariableDescriptionDefault Value
MANAGEMENT_SERVER_PORTPort for management endpoints8081
MANAGEMENT_ENDPOINT_HEALTH_GROUP_LIVENESS_INCLUDEHealth checks for liveness probesping,buildInfo
MANAGEMENT_ENDPOINT_HEALTH_GROUP_READINESS_INCLUDEHealth checks for readiness probesping,buildInfo,mongo
MANAGEMENT_HEALTH_KUBERNETES_ENABLEDEnable Kubernetes health checksfalse

​
Prometheus metrics configuration

Enable Prometheus metrics export for monitoring:
Environment VariableDescriptionDefault Value
MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLEDEnable Prometheus metrics exportfalse
The older form MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED also works (both resolve to the same setting). The property path above is the preferred form.

​
Troubleshooting

​
Common issues

Symptoms: Service fails to start with database connection errors.Solutions:
  1. Verify MongoDB connection string format and credentials
  2. Ensure MongoDB replica set is properly configured and accessible
  3. Check network connectivity between service and MongoDB instances
  4. Verify MongoDB user permissions and database access rights
Symptoms: Service cannot consume or produce Kafka messages.Solutions:
  1. Verify SPRING_KAFKA_BOOTSTRAP_SERVERS points to the correct broker(s)
  2. Check Kafka security protocol and authentication configuration
  3. Ensure network policies allow traffic to the Kafka cluster
  4. Verify topic names and consumer group assignments are correct
Symptoms: 401/403 errors when communicating with other FlowX services.Solutions:
  1. Verify OAuth client ID and client secret are correct
  2. Check OAuth server URL and realm configuration
  3. Ensure OAuth provider is accessible from the service
  4. Validate token endpoint URI configuration

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes

Kafka Authentication

Configure Kafka security and authentication

IAM Configuration

Identity and access management setup
Last modified on June 4, 2026