Microservices setup guides
Complete reference for deploying and configuring FlowX.AI microservices in your environment
FlowX.AI is built on a modern microservices architecture, allowing for scalable, resilient, and flexible deployments. Each microservice operates independently while collaborating with others to provide a complete enterprise solution.
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
Recommended installation order
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.
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
Core Components
Next, deploy these core services in order:
- Advancing Controller: Manages process advancement and orchestration
- Process Engine: Handles business process execution and state management
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
- License Core: License management and validation
- Events Gateway: Event routing and processing
- Document Plugin: Document generation and management
- Notification Plugin: Communication and alerts management
- Any additional plugins or extensions
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.
Common environment variables
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.
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_CLIENTCLIENTID | OAuth2 client ID for the service | flowx-admin-service | Yes |
SECURITY_OAUTH2_CLIENTCLIENTSECRET | OAuth2 client secret | secret | Yes |
SECURITY_OAUTH2_REALM | OAuth2 realm name | flowx | Yes |
SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTID | Service account client ID (for inter-service auth) | flowx-service-account | No* |
SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTSECRET | Service account client secret | secret | No* |
*Required for some services that need to make authenticated calls to other services
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
| 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 |
|---|---|---|---|
SPRING_KAFKA_BOOTSTRAPSERVERS | Comma-separated list of Kafka brokers | kafka-0:9092,kafka-1:9092,kafka-2:9092 | Yes |
SPRING_KAFKA_SECURITY_PROTOCOL | Security protocol for Kafka communication | 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 (50MB) | No |
Topic Naming Configuration
For services that communicate via Kafka, the topic naming follows a convention:
| Environment Variable | Description | Example Value | Required |
|---|---|---|---|
KAFKA_TOPIC_NAMING_SEPARATOR | Primary topic name separator | . | No |
KAFKA_TOPIC_NAMING_SEPARATOR2 | Secondary topic name separator | - | No |
KAFKA_TOPIC_NAMING_PACKAGE | Package prefix for topics | ai.flowx. | No |
KAFKA_TOPIC_NAMING_ENVIRONMENT | Environment segment | dev. | No |
KAFKA_TOPIC_NAMING_VERSION | Version suffix | .v1 | No |
The engine and other services listen for messages on topics with specific naming patterns. Ensure you use correct topic names to maintain proper inter-service communication.
Redis configuration
| Environment Variable | Description | Example Value | Required |
|---|---|---|---|
SPRING_REDIS_HOST | Redis server hostname | redis-master | Yes |
SPRING_REDIS_PORT | Redis server port | 6379 | Yes |
SPRING_REDIS_PASSWORD | Redis password | redisPassword789 | Yes |
REDIS_TTL | Cache TTL in milliseconds | 5000000 | No |
Logging configuration
| Environment Variable | Description | Example 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 |
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:
- Network Segmentation: Isolate microservices using network policies
- Secret Management: Use Kubernetes Secrets or a vault solution
- TLS Everywhere: Enable TLS for all service-to-service communication
- OAuth2 Scopes: Configure fine-grained OAuth2 scopes for services
- Resource Isolation: Use namespaces and pod security policies
- Regular Updates: Keep all components updated with security patches
- 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:
- Check Service Logs: Examine logs for error messages
- Verify Configurations: Ensure all required environment variables are set correctly
- Test Connectivity: Verify network connectivity between services
- Monitor Resources: Check CPU, memory, and disk usage
- Inspect Kafka Topics: Use Kafka tools to inspect message flow
- Review Database State: Examine database for data integrity issues
- Check OAuth2 Tokens: Verify token validity and permissions
Service-specific documentation
For detailed configuration of individual services, refer to:
Process Engine Setup
Admin Setup
Task Management Setup
Scheduler Core Setup
Data Search Setup
CMS Setup
Events Gateway Setup
Advancing Controller Setup
Application Manager Setup
Integration Setup
Runtime Manager Setup
Notifications Plugin Setup
Documents Plugin Setup
Microservices setup guides
Complete reference for deploying and configuring FlowX.AI microservices in your environment
FlowX.AI is built on a modern microservices architecture, allowing for scalable, resilient, and flexible deployments. Each microservice operates independently while collaborating with others to provide a complete enterprise solution.
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
Recommended installation order
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.
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
Core Components
Next, deploy these core services in order:
- Advancing Controller: Manages process advancement and orchestration
- Process Engine: Handles business process execution and state management
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
- License Core: License management and validation
- Events Gateway: Event routing and processing
- Document Plugin: Document generation and management
- Notification Plugin: Communication and alerts management
- Any additional plugins or extensions
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.
Common environment variables
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.
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_CLIENTCLIENTID | OAuth2 client ID for the service | flowx-admin-service | Yes |
SECURITY_OAUTH2_CLIENTCLIENTSECRET | OAuth2 client secret | secret | Yes |
SECURITY_OAUTH2_REALM | OAuth2 realm name | flowx | Yes |
SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTID | Service account client ID (for inter-service auth) | flowx-service-account | No* |
SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTSECRET | Service account client secret | secret | No* |
*Required for some services that need to make authenticated calls to other services
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
| 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 |
|---|---|---|---|
SPRING_KAFKA_BOOTSTRAPSERVERS | Comma-separated list of Kafka brokers | kafka-0:9092,kafka-1:9092,kafka-2:9092 | Yes |
SPRING_KAFKA_SECURITY_PROTOCOL | Security protocol for Kafka communication | 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 (50MB) | No |
Topic Naming Configuration
For services that communicate via Kafka, the topic naming follows a convention:
| Environment Variable | Description | Example Value | Required |
|---|---|---|---|
KAFKA_TOPIC_NAMING_SEPARATOR | Primary topic name separator | . | No |
KAFKA_TOPIC_NAMING_SEPARATOR2 | Secondary topic name separator | - | No |
KAFKA_TOPIC_NAMING_PACKAGE | Package prefix for topics | ai.flowx. | No |
KAFKA_TOPIC_NAMING_ENVIRONMENT | Environment segment | dev. | No |
KAFKA_TOPIC_NAMING_VERSION | Version suffix | .v1 | No |
The engine and other services listen for messages on topics with specific naming patterns. Ensure you use correct topic names to maintain proper inter-service communication.
Redis configuration
| Environment Variable | Description | Example Value | Required |
|---|---|---|---|
SPRING_REDIS_HOST | Redis server hostname | redis-master | Yes |
SPRING_REDIS_PORT | Redis server port | 6379 | Yes |
SPRING_REDIS_PASSWORD | Redis password | redisPassword789 | Yes |
REDIS_TTL | Cache TTL in milliseconds | 5000000 | No |
Logging configuration
| Environment Variable | Description | Example 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 |
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:
- Network Segmentation: Isolate microservices using network policies
- Secret Management: Use Kubernetes Secrets or a vault solution
- TLS Everywhere: Enable TLS for all service-to-service communication
- OAuth2 Scopes: Configure fine-grained OAuth2 scopes for services
- Resource Isolation: Use namespaces and pod security policies
- Regular Updates: Keep all components updated with security patches
- 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:
- Check Service Logs: Examine logs for error messages
- Verify Configurations: Ensure all required environment variables are set correctly
- Test Connectivity: Verify network connectivity between services
- Monitor Resources: Check CPU, memory, and disk usage
- Inspect Kafka Topics: Use Kafka tools to inspect message flow
- Review Database State: Examine database for data integrity issues
- Check OAuth2 Tokens: Verify token validity and permissions
Service-specific documentation
For detailed configuration of individual services, refer to: