> ## 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.
# FlowX Advancing Controller setup
> This guide provides step-by-step instructions to help you configure and deploy the Advancing Controller effectively.
## Infrastructure prerequisites
Before setting up the Advancing Controller, ensure the following components are properly set up:
* **FlowX.AI Engine Deployment**: The Advancing Controller depends on the FlowX Engine and must be deployed in the same environment. Refer to the FlowX Engine [**setup guide**](./flowx-engine-setup-guide/engine-setup) for more information on setting up the Engine.
* **Database Instance**: The Advancing Controller uses a PostgreSQL or Oracle Database instance as its database.
***
## Dependencies
Ensure the following dependencies are met:
* [Database](#database-configuration): Properly configured database instance.
* [Datasource](#configuring-datasource): Configuration details for connecting to the database.
* [FlowX.AI Engine](./flowx-engine-setup-guide/engine-setup): Must be set up and running. Refer to the FlowX Engine setup guide.
### Database compatibility
The Advancing Controller supports both PostgreSQL and Oracle databases. However, the FlowX.AI Engine and the Advancing Controller must be configured to use the same type of database at any given time. The FlowX.AI Engine employs two databases: one shared with the FlowX.AI Admin microservice for process metadata and instances, and the other dedicated to advancement.
Mixing PostgreSQL and Oracle Database is not supported; both databases must be of the same type.
***
## Database configuration
### PostgreSQL
A basic PostgreSQL configuration for Advancing.
If the parallel advancing configuration already exists, you must reset the 'advancing' database by executing the SQL command `DROP DATABASE advancing;`. Once the database has been dropped, the Liquibase script will automatically re-enable it.
***
## Configuration
The Advancing Controller uses a PostgreSQL or an Oracle database as a dependency.
* Ensure that the user, password, connection link, and database name are correctly configured. If these details are not configured correctly, errors will occur at startup.
* The datasource is configured automatically via a Liquibase script inside the engine. All updates will include migration scripts.
### Configuring datasource
If you need to change the datasource configuration detail, you can use the following environment variables:
| Variable | Description | Default Value |
| ------------------------------------------------ | --------------------------------------------------------- | --------------------------------------------- |
| `SPRING_DATASOURCE_URL` | JDBC URL for database connection | `jdbc:postgresql://postgresql:5432/advancing` |
| `SPRING_DATASOURCE_DRIVERCLASSNAME` | JDBC driver class name | `org.postgresql.Driver` |
| `SPRING_DATASOURCE_USERNAME` | Database username | `postgres` |
| `SPRING_DATASOURCE_PASSWORD` | Database password | `[your-secure-password]` |
| `SPRING_JPA_DATABASE` | Database type (accepted values: `oracle` or `postgresql`) | `postgresql` |
| `SPRING_JPA_SHOWSQL` | Toggle SQL query logging | `false` |
| `SPRING_JPA_PROPERTIES_HIBERNATE_DEFAULT_SCHEMA` | Default database schema (❗️only for Oracle DBs) | `public` |
| `SPRING_LIQUIBASE_CHANGELOG` | Path to Liquibase changelog for database migrations | `classpath:config/liquibase/master.xml` |
It's important to keep in mind that the Advancing Controller is tightly integrated with the FlowX.AI Engine. Therefore, it is crucial to ensure that both the Engine and the Advancing Controller are configured correctly and are in sync.
***
## Health monitoring
| Variable | Description | Default Value |
| ------------------------------ | ----------------------------- | ------------- |
| `MANAGEMENT_HEALTH_DB_ENABLED` | Enable database health checks | `true` |
***
## Troubleshooting
### Common issues
**Symptoms:** Process instances remain in a pending state and do not advance to the next node.
**Solutions:**
1. Check Kafka connectivity and verify that the Advancing Controller can reach the Kafka brokers
2. Review the Advancing Controller logs for errors or warnings related to message consumption
3. Monitor consumer group lag to determine if messages are accumulating without being processed
4. Verify that the FlowX Engine is running and responsive
**Symptoms:** The service crashes or exits during startup with connection errors.
**Solutions:**
1. Verify the PostgreSQL (or Oracle) connection string and credentials are correct
2. Check that the Kafka broker configuration is valid and the brokers are reachable
3. Ensure the PostgreSQL (or Oracle) database is accessible and the `advancing` database exists
4. Review the Liquibase migration logs for schema issues
**Symptoms:** Logs show timeout exceptions when advancing tokens between nodes.
**Solutions:**
1. Review process complexity — deeply nested subprocesses or large parallel gateways may require longer timeouts
2. Monitor Kafka response times to identify broker-side latency
3. Verify that downstream services responding via Kafka are healthy and not overloaded
**Symptoms:** The Advancing Controller pod shows consistently high CPU utilization.
**Solutions:**
1. Check thread pool settings and reduce concurrency if the system is over-provisioned
2. Monitor the number of concurrent process instances being advanced
3. Review Kafka consumer configuration — a high number of partitions with aggressive polling can increase CPU load
4. Consider scaling horizontally by adding additional replicas
***
## Related resources
Learn how the Advancing Controller manages process instance progression
Configure the FlowX Engine that the Advancing Controller depends on
Complete Redis setup including Sentinel and Cluster modes