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

# Microservices setup guides

> Complete reference for deploying and configuring FlowX.AI microservices in your environment

This page is the starting point for deploying FlowX.AI in your own environment. It covers deployment prerequisites, container-image and registry configuration, the environment variables shared across services, deployment best practices, and troubleshooting, and it links to the per-service setup guide for every FlowX.AI microservice. Each service ships as a Docker container, so you can deploy on Kubernetes or any other container orchestration platform.

## Deployment strategy

Deploying FlowX.AI microservices involves breaking down the application into modular components that can be independently deployed, scaled, and maintained. All microservices are delivered as Docker containers, making them suitable for deployment on any container orchestration platform, such as Kubernetes or Docker Swarm.

### Deployment prerequisites

Before beginning the deployment process, ensure you have:

* A Kubernetes cluster or Docker environment
* Access to a container registry
* Persistent storage for databases
* Network policies configured for inter-service communication
* Resource quotas and limits defined for each environment

### Container images and registry

Every FlowX.AI service ships as a Docker image, and each service chart resolves its image from three values: the registry, the repository (the image name), and the tag.

Starting with **5.9.4**, the registry and the image name are separate fields:

```yaml theme={"dark"}
image:
  registry: <your-registry>
  repository: ai-gateway
```

On **5.9.0 through 5.9.3**, the two are a single combined path:

```yaml theme={"dark"}
image:
  repository: <your-registry>/ai-gateway
```

The recommended way to point every chart at your own registry is `global.imageRegistry`. It takes precedence over each chart's own `image.registry`, so mirrored or air-gapped deployments set it once instead of overriding image values service by service:

```yaml theme={"dark"}
global:
  imageRegistry: <your-registry>
  imagePullSecrets:
    - my-registry-credentials
```

> [!WARNING]
>
> On **5.9.4 and later**, do not leave the registry inside `image.repository` while `image.registry` or `global.imageRegistry` is also set. The registry is prepended twice and the image fails to resolve. If you previously used the combined path, move the registry portion out and let `image.repository` hold just the image name.

### Recommended installation order

> [!TIP]
>
> Following the correct installation sequence is crucial for a successful deployment. This ordered approach prevents dependency issues and ensures each service has the required dependencies available when it initializes.

**1. Infrastructure Components**

First, deploy the foundational infrastructure:

* **Databases**: PostgreSQL/Oracle for relational data, MongoDB for document storage
* **Message Broker**: Kafka and ZooKeeper
* **Caching**: Redis
* **Identity Management**: Keycloak or other OAuth2 provider

**2. Core Components**

Next, deploy these core services in order:

1. **Advancing Controller**: Manages process advancement and orchestration
2. **Process Engine**: Handles business process execution and state management

**3. Backend Services**

Once the core components are operational, deploy these services (can be deployed in parallel):

* **Admin Service**: Platform administration and configuration management
* **Audit Core**: Compliance auditing and activity tracking
* **Task Management**: Human task assignment and workflow
* **Scheduler Core**: Job scheduling and time-based operations
* **Data Search**: Indexing and searching capabilities
* **Events Gateway**: Event routing and processing
* **Document Plugin**: Document generation and management
* **Notification Plugin**: Communication and alerts management
* **Any additional plugins or extensions**

**4. AI Platform Services**

Deploy the AI Platform services for intelligent automation capabilities:

The AI Platform is a set of Python services:

* **Planner**: Intent understanding and task orchestration
* **Agent Builder**: Configuration and runtime for low-code AI nodes
* **Knowledgebase RAG**: Retrieval-augmented generation over the knowledge base
* **Embedder**: Embedding generation
* **Knowledgebase Indexer v2**: Event-driven retrieval-vector indexing
* **AI Developer**: Automated code generation capabilities
* **AI Analyst**: Process analysis and optimization
* **AI Designer**: UI generation and design automation
* **AI Assistant**: FlowX.AI documentation assistant
* **KB Enrichment**: Design-time document intelligence over knowledge-base documents (new in 5.9.1, replaces `di-platform`)

> [!NOTE]
>
> AI *features* (chat, AI nodes, agents) are optional, but the AI services themselves are **required infrastructure** — `integration-designer` has hard startup dependencies on AI Platform endpoints and will not start without them. See the [AI Platform setup guide](https://docs.flowx.ai/6.x/setup-guides/ai-platform-setup.md) for how to run FlowX without AI features.

**5. Frontend Components**

Finally, deploy the frontend services:

* **Designer**: Process design environment for business analysts
* **Web Components**: UI components for custom applications
* **Customer-facing UIs and portals**

## Environment variables reference

Environment variables are the primary configuration mechanism for FlowX.AI microservices. They provide a secure and flexible way to customize service behavior without modifying the container images.

The following sections detail the most commonly used environment variables across FlowX.AI microservices. For service-specific variables, refer to the dedicated setup guides for each component.

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Authorization & access management

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the OAuth2/OIDC server | `https://keycloak.example.com/auth` | Yes |
| `SECURITY_OAUTH2_CLIENT_CLIENTID` | OAuth2 client ID for the service | `flowx-admin-service` | Yes |
| `SECURITY_OAUTH2_CLIENT_CLIENTSECRET` | OAuth2 client secret | `secret` | Yes |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | `flowx` | Yes |

### Database configuration

#### PostgreSQL/Oracle

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL | `jdbc:postgresql://postgres:5432/flowx` | Yes |
| `SPRING_DATASOURCE_USERNAME` | Database username | `flowx_user` | Yes |
| `SPRING_DATASOURCE_PASSWORD` | Database password | `securePassword123` | Yes |
| `SPRING_DATASOURCE_DRIVERCLASSNAME` | JDBC driver class (Oracle only) | `oracle.jdbc.OracleDriver` | Yes\* |
| `SPRING_JPA_PROPERTIES_HIBERNATE_DEFAULTSCHEMA` | Default schema (Oracle only) | `FLOWX` | Yes\* |

\*Required only for Oracle databases

#### MongoDB (NoSQL)

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | `mongodb://mongo1,mongo2,mongo3:27017/flowx?replicaSet=rs0` | Yes |
| `DB_USERNAME` | MongoDB username for services that need it | `flowx_mongo_user` | Yes |
| `DB_PASSWORD` | MongoDB password | `mongoSecurePass456` | Yes |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | Enable runtime MongoDB connection | `true` | No |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | URI for runtime MongoDB connection | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-runtime:27017/app-runtime` | No\* |

\*Required if runtime MongoDB connection is enabled

### Kafka configuration

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `KAFKA_BOOTSTRAP_SERVERS` | Comma-separated list of Kafka brokers (preferred) | `kafka-0:9092,kafka-1:9092,kafka-2:9092` | Yes\* |
| `SPRING_KAFKA_BOOTSTRAPSERVERS` | Legacy property for Kafka brokers (fallback) | `kafka-0:9092,kafka-1:9092,kafka-2:9092` | Yes\* |
| `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka (preferred) | `SASL_PLAINTEXT` | No |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Legacy property for security protocol (fallback) | `SASL_PLAINTEXT` | No |
| `SPRING_KAFKA_CONSUMER_GROUPID` | Consumer group ID | `flowx-process-engine-group` | Yes |
| `KAFKA_CONSUMER_THREADS` | Number of Kafka consumer threads | `5` | No |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval for auth exceptions (seconds) | `10` | No |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka message size (bytes) | `52428800` (50 MB) | No |

> [!NOTE]
>
> The `KAFKA_BOOTSTRAP_SERVERS` and `KAFKA_SECURITY_PROTOCOL` properties are preferred and aligned across all services. The legacy `SPRING_KAFKA_BOOTSTRAPSERVERS` and `SPRING_KAFKA_SECURITY_PROTOCOL` properties remain supported for backwards compatibility. If both are set, the new properties take precedence.
>
> \*At least one of `KAFKA_BOOTSTRAP_SERVERS` or `SPRING_KAFKA_BOOTSTRAPSERVERS` must be set.

#### Kafka authentication profile

FlowX.AI supports enabling Kafka authentication across all Java microservices using the `kafka-auth` Spring configuration profile. This feature simplifies the activation of secure Kafka communication.

To enable Kafka authentication, set the `SPRING_PROFILES_ACTIVE` environment variable:

```bash theme={"dark"}
SPRING_PROFILES_ACTIVE=kafka-auth
```

> [!NOTE]
>
> You can activate multiple profiles by separating them with commas: `SPRING_PROFILES_ACTIVE=dev,kafka-auth`

**Additional environment variables for OAuth-based Kafka authentication:**

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID used to authenticate with the token endpoint | `kafka-client` | Yes\* |
| `KAFKA_OAUTH_CLIENT_SECRET` | Secret associated with the OAuth client ID | `kafka-secret` | Yes\* |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint URI from which access tokens are obtained | `https://keycloak.example.com/auth/token` | Yes\* |

\*Required when `kafka-auth` profile is active

> [!WARNING]
>
> The kafka-auth profile enforces SASL/OAUTHBEARER with plaintext transport. Ensure secure networking (VPN, mTLS) is configured where required.

For more details, see the [Kafka Authentication Configuration](https://docs.flowx.ai/6.x/setup-guides/kafka-authentication-config.md) guide.

### Redis configuration

FlowX.AI microservices use Redis for caching and real-time data management. Redis can be deployed in three modes: Standalone, Sentinel (high availability), and Cluster (horizontal scaling).

**Quick reference for common Redis variables:**

| Environment Variable | Description | Example Value | Mode |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | Standalone |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | Standalone |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | `yourpassword` | All modes |
| `SPRING_DATA_REDIS_SENTINEL_MASTER` | Sentinel master name | `mymaster` | Sentinel |
| `SPRING_DATA_REDIS_SENTINEL_NODES` | Sentinel nodes list | `host1:26379,host2:26379` | Sentinel |
| `SPRING_DATA_REDIS_CLUSTER_NODES` | Cluster nodes list | `host1:6379,host2:6379` | Cluster |

> [!NOTE]
>
> For complete Redis configuration including all deployment modes, SSL/TLS setup, and troubleshooting, see the [Redis Configuration](https://docs.flowx.ai/6.x/setup-guides/redis-configuration.md) guide.

### Logging configuration

| Environment Variable | Description | Default Value | Required |
| - | - | - | - |
| `LOGGING_LEVEL_ROOT` | Root logging level | `INFO` | No |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `DEBUG` | No |
| `LOGGING_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `WARN` | No |
| `LOGGING_LEVEL_KAFKA` | Kafka client logging level | `WARN` | No |
| `LOGGING_LEVEL_REDIS` | Redis client logging level | `OFF` | No |

#### Changing log levels at runtime

> [!WARNING]
>
> **Changed in FlowX.AI 5.9.5.** The `loggers` actuator endpoint is no longer in the default exposure list, so it is not reachable by default on 5.9.5 and later. To keep changing log levels at runtime, add `loggers` to `MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE` (for example `health,info,metrics,prometheus,loggers`). Otherwise, set log levels with the `LOGGING_LEVEL_*` environment variables and restart the service.

All FlowX microservices support dynamic log level adjustment without requiring a restart. This capability uses Spring Boot Actuator's loggers endpoint and is particularly useful for troubleshooting production issues.

**Prerequisites:**

Ensure the `loggers` endpoint is exposed in your management endpoints configuration:

**Example usage:**

```bash theme={"dark"}
curl 'http://localhost:8081/manage/actuator/loggers/ai.flowx' \
  -i -X POST \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel":"DEBUG"}'
```

Replace `ai.flowx` with the specific logger package you want to modify.

**Available log levels:** `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`

> [!WARNING]
>
> Dynamic log level changes are not persisted. They will reset to the configured values when the service restarts. Using `DEBUG` or `TRACE` levels in production may impact performance and generate large log volumes.

## Deployment best practices

### High availability considerations

For production environments, configure these high availability features:

* **Database Clustering**: Implement PostgreSQL/Oracle with replication
* **MongoDB Replica Sets**: Deploy MongoDB as a replica set with at least 3 nodes
* **Kafka Clustering**: Use at least 3 Kafka brokers with replication factor ≥ 3
* **Redis Sentinel/Cluster**: Configure Redis for high availability
* **Service Replicas**: Run multiple instances of each microservice
* **Load Balancing**: Implement proper load balancing for service instances
* **Affinity/Anti-Affinity Rules**: Distribute service instances across nodes

### Security recommendations

Secure your FlowX.AI deployment with these measures:

1. **Network Segmentation**: Isolate microservices using network policies
2. **Secret Management**: Use Kubernetes Secrets or a vault solution
3. **TLS Everywhere**: Enable TLS for all service-to-service communication
4. **OAuth2 Scopes**: Configure fine-grained OAuth2 scopes for services
5. **Resource Isolation**: Use namespaces and pod security policies
6. **Regular Updates**: Keep all components updated with security patches
7. **Audit Logging**: Enable comprehensive audit logging via the Audit Core service

## Troubleshooting

### Common issues and solutions

| Issue | Possible cause | Solution |
| - | - | - |
| Service fails to start | Missing environment variables | Check logs for "Configuration property not found" errors |
| Database connection errors | Incorrect credentials or URL | Verify database connection parameters |
| Services can't communicate | Kafka misconfiguration | Ensure topic names match between producer and consumer services |
| Authentication failures | OAuth2 configuration issues | Verify client IDs, secrets, and server URLs |
| Performance degradation | Insufficient resources | Monitor CPU/memory usage and scale resources appropriately |
| Data inconsistency | Redis cache not synchronized | Check Redis connection and consider cache invalidation |

### Diagnostic procedures

When troubleshooting FlowX.AI microservices:

1. **Check Service Logs**: Examine logs for error messages
2. **Verify Configurations**: Ensure all required environment variables are set correctly
3. **Test Connectivity**: Verify network connectivity between services
4. **Monitor Resources**: Check CPU, memory, and disk usage
5. **Inspect Kafka Topics**: Use Kafka tools to inspect message flow
6. **Review Database State**: Examine database for data integrity issues
7. **Check OAuth2 Tokens**: Verify token validity and permissions

## Service-specific documentation

For detailed configuration of individual services, refer to:

### Core platform components

> [card] [Process Engine Setup](https://docs.flowx.ai/6.x/setup-guides/flowx-engine-setup-guide/engine-setup.md)

> [card] [Admin Setup](https://docs.flowx.ai/6.x/setup-guides/admin-setup-guide.md)

> [card] [Advancing Controller Setup](https://docs.flowx.ai/6.x/setup-guides/advancing-controller-setup-guide.md)

> [card] [Application Manager Setup](https://docs.flowx.ai/6.x/setup-guides/application-manager.md)

> [card] [Runtime Manager Setup](https://docs.flowx.ai/6.x/setup-guides/runtime-manager.md)

> [card] [Scheduler Core Setup](https://docs.flowx.ai/6.x/setup-guides/scheduler-setup-guide.md)

> [card] [Audit Setup](https://docs.flowx.ai/6.x/setup-guides/audit-setup-guide.md)

> [card] [Authorization Setup](https://docs.flowx.ai/6.x/setup-guides/authorization-setup-guide.md)

> [card] [Task Management Setup](https://docs.flowx.ai/6.x/setup-guides/task-management-plugin-setup.md)

> [card] [Notifications Setup](https://docs.flowx.ai/6.x/setup-guides/notifications-plugin-setup.md)

> [card] [Document Setup](https://docs.flowx.ai/6.x/setup-guides/documents-plugin-setup.md)

> [card] [Events Gateway Setup](https://docs.flowx.ai/6.x/setup-guides/events-gateway-setup.md)

### AI Platform services

> [!NOTE]
>
> The AI Platform is a suite of AI services that provide intelligent automation capabilities across the entire application lifecycle.

> [card] [AI Platform Setup](https://docs.flowx.ai/6.x/setup-guides/ai-platform-setup.md)

### Plugins & extensions

> [card] [OCR Plugin Setup](https://docs.flowx.ai/6.x/setup-guides/plugins-setup-guide/ocr-plugin-setup.md)

> [card] [Reporting Setup](https://docs.flowx.ai/6.x/setup-guides/plugins-setup-guide/reporting-setup.md)

### Integration & data services

> [card] [Integration Designer Setup](https://docs.flowx.ai/6.x/setup-guides/integration-designer-setup.md)

> [card] [Data Search Setup](https://docs.flowx.ai/6.x/setup-guides/search-data-service-setup-guide.md)

> [card] [Data Sync Setup](https://docs.flowx.ai/6.x/setup-guides/data-sync.md)

> [card] [NoSQL DB Runner Setup](https://docs.flowx.ai/6.x/setup-guides/nosql-db-runner.md)

### User interface & designer

> [card] [Designer Setup](https://docs.flowx.ai/6.x/setup-guides/designer-setup-guide.md)

> [card] [CMS Setup](https://docs.flowx.ai/6.x/setup-guides/cms-setup.md)

### Infrastructure & extensions

> [card] [SpiceDB Setup](https://docs.flowx.ai/6.x/setup-guides/spicedb.md)

### Observability & configuration

> [card] [OpenTelemetry Config](https://docs.flowx.ai/6.x/setup-guides/open-telemetry-config.md)

> [card] [OT Default Properties](https://docs.flowx.ai/6.x/setup-guides/ot-default-properties.md)


## Related topics

- [Scheduler setup](https://docs.flowx.ai/6.x/setup-guides/scheduler-setup-guide.md)
- [Audit setup](https://docs.flowx.ai/6.x/setup-guides/audit-setup-guide.md)
- [Organization Manager setup](https://docs.flowx.ai/6.x/setup-guides/organization-manager-setup.md)
- [Email Gateway setup](https://docs.flowx.ai/6.x/setup-guides/email-gateway-setup.md)
- [Authorization system setup](https://docs.flowx.ai/6.x/setup-guides/authorization-setup-guide.md)


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