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

# NoSQL DB Runner

> Set up the NoSQL DB Runner microservice that powers FlowX Database with MongoDB and Azure Cosmos DB support.

## 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 Variable      | Description                                   | Default Value                                                                                                                                                    |
| ------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DB_USERNAME`             | MongoDB username for the service              | `nosql-db-runner`                                                                                                                                                |
| `DB_PASSWORD`             | MongoDB password (should be stored as secret) | `secret(mongodb-generic)`                                                                                                                                        |
| `SPRING_DATA_MONGODB_URI` | Complete MongoDB connection string            | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/nosql-db-runner` |

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

### 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 Variable                                                        | Description                                                                                                                                           | Default Value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_TYPE`                                                             | Token validation mechanism (JWT public key validation)                                                                                                | `jwt-public-key`                                                                                   |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                                                                                    |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002`                                                             |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`                   | URL of the organization-manager service, used by the security library                                                                                 | `http://organization-manager:80`                                                                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-nosql-db-runner-sa`                                                                         |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Warning>
  **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](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

### 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 Variable                | Description                                                       | Default Value |
| ----------------------------------- | ----------------------------------------------------------------- | ------------- |
| `FLOWX_RUNOPERATIONS_DOCUMENTLIMIT` | Maximum number of documents to be processed in a single operation | `1000`        |

### External MongoDB connection caching

| Environment Variable                        | Description                                                             | Default Value |
| ------------------------------------------- | ----------------------------------------------------------------------- | ------------- |
| `FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum number of cached external MongoDB connections                   | `100`         |
| `FLOWX_MONGO_CONNECTIONS_CACHE_TTL`         | Time-to-live for cached connections (duration format, e.g. `1d`, `12h`) | `1d`          |

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

### Oracle Database connection pooling

| Environment Variable                            | Description                                                                  | Default Value |
| ----------------------------------------------- | ---------------------------------------------------------------------------- | ------------- |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES`      | Maximum cached JDBC connection pools                                         | `100`         |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL`              | Time-to-live for cached connection pools (duration format, e.g. `1d`, `12h`) | `1d`          |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE`              | Maximum HikariCP pool size per Oracle data source                            | `5`           |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout                                                      | `10`          |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT`                  | Default row cap on `SELECT` responses                                        | `1000`        |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS`      | Query execution timeout                                                      | `30`          |

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

### Configuring logging

Control log levels for different components of the service:

| Environment Variable  | Description                                   | Default Value        |
| --------------------- | --------------------------------------------- | -------------------- |
| `LOGGING_CONFIG_FILE` | Path to the logging configuration file        | `logback-spring.xml` |
| `LOGGING_LEVEL_ROOT`  | Root logger level for the Spring Boot service | `INFO`               |
| `LOGGING_LEVEL_APP`   | Application-specific log level                | `INFO`               |

<Warning>
  Using DEBUG log levels in production environments may impact performance and generate large log volumes. Consider using INFO or WARN levels for production deployments.
</Warning>

### Configuring application management

Configure management endpoints and monitoring capabilities:

| Environment Variable                                 | Description                        | Default Value          |
| ---------------------------------------------------- | ---------------------------------- | ---------------------- |
| `MANAGEMENT_SERVER_PORT`                             | Port for management endpoints      | `8081`                 |
| `MANAGEMENT_ENDPOINT_HEALTH_GROUP_LIVENESS_INCLUDE`  | Health checks for liveness probes  | `ping,buildInfo`       |
| `MANAGEMENT_ENDPOINT_HEALTH_GROUP_READINESS_INCLUDE` | Health checks for readiness probes | `ping,buildInfo,mongo` |
| `MANAGEMENT_HEALTH_KUBERNETES_ENABLED`               | Enable Kubernetes health checks    | `false`                |

### Prometheus metrics configuration

Enable Prometheus metrics export for monitoring:

| Environment Variable                           | Description                      | Default Value |
| ---------------------------------------------- | -------------------------------- | ------------- |
| `MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLED` | Enable Prometheus metrics export | `false`       |

<Info>
  The older form `MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED` also works (both resolve to the same setting). The property path above is the preferred form.
</Info>

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="MongoDB connection failures">
    **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
  </Accordion>

  <Accordion title="Kafka connectivity issues">
    **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
  </Accordion>

  <Accordion title="OAuth authentication errors">
    **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
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="Kafka Authentication" icon="lock" href="./kafka-authentication-config">
    Configure Kafka security and authentication
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>
</CardGroup>