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.

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

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 (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
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 (50 MB)	No

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:

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:

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