Running Flowable REST with Docker Compose and PostgreSQL: when a team needs it
A team reaches for the Flowable REST application in containers when it needs HTTP access to the BPMN, CMMN and DMN engines for evaluation or a first shared environment, with PostgreSQL as the database. The REST application exposes the engines over HTTP instead of requiring each application to embed them as a JAR, which means developers, testers and front-end teams can deploy definitions, start instances and query tasks without building a Java service first. The Flowable getting started guide describes this HTTP option alongside embedding the engines in Java SE, servlet container, Spring and Java EE applications. Flowable 8.0.0, released on February 27, 2026, is the current major line, and the engines are licensed under Apache 2.0, so a team can run the stack without a commercial agreement.
Compose is a reasonable starting point when the goal is to learn the data model, test a few process definitions against a real database, or give a small group a disposable environment. It becomes insufficient once the stack needs controlled credentials, backups of the database, defined resource limits, TLS termination, log retention, or a deployment path that repeats the same way across environments. Before you run anything, confirm the Compose file, image tag and database image match the Flowable version you intend to pin, because the project's Compose configurations change with releases and a file copied from an older branch can point at the wrong images or settings. Read the file rather than assuming its defaults are safe.
Plan the move from demo to production as its own piece of work. The default credentials in the sample configuration must be replaced, the database must be placed on storage with a tested recovery path, and the REST application's authentication mode must be chosen deliberately rather than inherited from the demo. Ask your team to confirm which Flowable release line its applications target, since the Java, Spring and Jakarta baseline differs between major versions and a stack built for one line will not simply carry over to another. Treat the Compose setup as a learning environment until those decisions are written down and verified in your own infrastructure.
Which deployment options fit which stage
This table compares the four decisions a team makes when moving Flowable REST from the Compose demo to something it can run in production. Read each row as a choice, what it changes for operations, and what remains your responsibility. The main takeaway is that the project's Compose files settle the topology quickly, while database ownership, backups and identity stay with your team.
| Decision | What it changes operationally | What the team still owns |
|---|---|---|
| Single REST container or the HAProxy load-balanced variant | A single container is the simplest topology to start and inspect. The HAProxy variant puts several REST instances behind one entry point, so the team must watch load distribution and instance health. | Choosing the instance count, health checks, TLS termination at the proxy, and confirming that every node points at the same database. |
| PostgreSQL or another supported database type | The configuration docs list H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server. Changing the database changes JDBC drivers, schema handling and backup tooling. | Selecting the database that matches your standards, sizing it, and confirming the driver and version combination with your DBA and the Flowable docs. |
| Demo default database or an external PostgreSQL | The demo stack keeps data in a container that is convenient for trials. An external PostgreSQL moves storage, backups and retention to infrastructure you already run. | Provisioning the database, credentials, backups, restore tests, connection limits and network access rules between the REST containers and the database. |
| Default identity or a replaced identity service | The default identity setup suits evaluation only. Replacing it with an override of IdmIdentityServiceImpl or an IdmIdentityService implementation, such as the LDAP reference, changes how users and groups are resolved. | Writing and testing the identity service, mapping groups to your directory, changing default accounts, and confirming authorization checks in your own application. |
Standing up the Compose stack and confirming it works
This sequence takes a pinned Flowable Compose configuration from review to a running REST application backed by PostgreSQL, with a clear check at each stage so that a failure is caught before it reaches production settings.
Pin the Flowable version before downloading anything
Choose the Flowable release line you will run and record it in your change ticket. Obtain the Compose configuration from the Flowable project for that exact version rather than from a branch or a copy in an old repository, and store it in your own version control. Your engineer confirms the version tag matches the release notes they reviewed. Done when the configuration is committed to your repository with the version recorded in the commit message and no floating image tags remain in the file.
Review every service and environment variable first
Before the first start, read each service definition, its image reference, exposed ports, volumes, health settings and environment variables. Mark every credential, default account and host name that the project supplies as a placeholder that must change. Confirm which services are demo-only and which you will keep. Your security engineer signs off on the list of values to replace. Done when the review notes list each value to change and each service you intend to run, with no unreviewed entries left in the file.
Replace demo values with your own secrets
Move every credential you marked into your secret store or an untracked environment file, and remove literal demo values from committed configuration. Generate new database and application passwords according to your password policy. Confirm the file contains references to secrets rather than values by searching for the original defaults. Done when a search of the repository for each default value returns no matches and the stack reads its secrets from the location you chose.
Start PostgreSQL and confirm it accepts connections
Bring up only the database service first so that a failure is isolated from the application. Check the container status and logs for a completed initialization. From a client on the same Compose network, connect with the application database user and run a trivial query. Done when the database reports ready in its logs and the test query returns a result using the application account rather than a superuser.
Start the REST application and watch the first boot
Start the Flowable REST service and follow its logs from the first line. Look for the engine startup messages for each enabled engine and for schema creation or validation against the database. Note any database connection error, missing driver or property error, since these stop the engines from starting. Done when the logs show every enabled engine initializing and the database tables are present, confirmed by listing tables from the database client.
Check the health endpoint and the REST responses
Call the health endpoint exposed by the application and confirm it reports the service as up, including its database check. Then call a read-only REST endpoint for the process engine using the credentials you set in the earlier steps, and confirm an authenticated request succeeds while an unauthenticated one is refused. Done when the health response reports up, the authenticated call returns a successful status, and the unauthenticated call is rejected.
Record the baseline before changing settings
Save the working configuration, the image version, the list of changed values (without their secret contents), the boot log excerpt and the health and REST check results as the baseline for this environment. Your team uses this record to compare later changes and to confirm the stack matches what was reviewed. Done when the baseline is stored in your change system and any later edit to the configuration is compared against it.
Demo defaults versus production settings
The project's Compose configuration is built to start quickly on a single workstation, so its defaults favor convenience over the controls a regulated environment needs. Read every file before the first docker compose up, because each default sets the starting point for the checks below. The Flowable configuration docs explain the properties that environment variables map to.
- Default credentials: Find every username and password in the Compose files, environment blocks and REST security settings. Assume anyone with the repository can read them.
- Database account: Check whether the PostgreSQL service creates a superuser that the engine also uses, and whether its password sits in plain text.
- Published ports: List each host port, including the REST port and any management port, and confirm whether the actuator endpoint answers without authentication.
- Transport: Confirm that the stack serves plain HTTP. Treat demo settings as no TLS termination at all.
- Storage and schema: Check whether PostgreSQL data lives in a named volume that is removed with the stack, and whether the engine creates or updates tables on startup.
Before any environment beyond a laptop, write down each default you found and name the person who will replace it.
A production-oriented stack keeps the same engine and REST application but replaces demo choices with settings that your security and platform teams own. Make these decisions before the first deploy, then verify each one against the running containers, not only the files that describe them.
- Credentials: Generate unique database and REST credentials, inject them at runtime from your secrets store, and keep them out of Compose files and image layers.
- Database access: Create a dedicated role for the engine with rights to its own schema, and apply the password policy your DBA enforces.
- Exposure: Publish only the REST port that your gateway or load balancer needs. Restrict the actuator endpoint to the monitoring network, and disable any endpoint you do not use.
- TLS: Terminate TLS at a reverse proxy or load balancer you operate, using certificates from your PKI. Decide whether traffic between the proxy and the REST application is also encrypted.
- Persistence and resources: Place PostgreSQL data on storage with replication or snapshots you control, and set CPU and memory limits for each container.
Ask your DBA and security team to sign off each row against the running environment, and keep the sign-off with the deployment record.
Some controls matter most after go-live, when the stack is running, tables keep growing and credentials need rotation. These checks are the ones teams most often skip because the stack appears to work, so assign an owner and a review frequency to each before production traffic arrives.
- Schema policy: Decide whether the engine updates tables at startup or whether DBAs apply scripts through your change process. Disable automatic changes in production if your process requires it, and plan each version upgrade as a separate change.
- Backups: Schedule PostgreSQL backups, encrypt them, and store copies outside the host. Test restores on a schedule, because a backup job that completes proves little on its own.
- Log handling: Route container and engine logs to your central store, mask any value that could contain a credential, and set retention that matches your policy.
- Connection capacity: Watch database connection counts as you add REST instances, since each instance draws from the same database.
- Credential rotation: Rotate database and REST credentials on a schedule, then confirm that the stack restarts cleanly after each rotation.
Record the owner, the check frequency and the evidence for each control, so the next review can confirm that it still operates.
Which default credentials and endpoints to change first
A Compose stack built for evaluation ships with accounts, ports and admin interfaces meant to get a team started quickly. The cards below cover the controls to review before any shared environment sees traffic, and each one should be checked against the project's current Compose files and REST application configuration rather than assumed.
Replace every default account and password
Start with the REST application's built-in users and the database account defined in the Compose file. Each default login must be replaced with a unique credential, and the old values should be confirmed as gone in the running containers, not only in the file you edited. Check the REST application's authentication settings to see where users are defined and whether the default accounts are still active. Record who owns each credential so rotation has a clear owner.
Keep database secrets out of files and images
Compose files committed to Git or baked into an image expose database passwords to anyone who can read the repository or pull the image. Move secrets into environment files excluded from version control, Docker secrets, or your organization's secret manager, and confirm with docker history and a repository search that no password remains in an image layer or a tracked file. Ask who can read the host's environment file and whether the database port is reachable from outside the Compose network.
Limit exposed REST and actuator endpoints
The REST application and the Spring Boot actuator expose more than most deployments need. The actuator includes a monitoring endpoint at /actuator/flowable that reports on running processes, so decide whether it should be reachable at all outside the internal network. Disable the endpoints you do not use, restrict management ports to an internal interface, and test each remaining endpoint with an unauthenticated request to confirm it returns the response you expect.
Protect the HAProxy admin and stats interface
The load-balanced variant places HAProxy in front of the REST nodes, and HAProxy may offer a stats page or admin socket. Confirm whether the stats listener is enabled in the configuration you deploy, bind it to a management address, and require authentication before exposing it through any published port. Remove or restrict any admin socket so only the operations group can reach it. Check the HAProxy configuration file itself, since defaults can differ between example files and your version.
Restrict network paths between containers
Containers on the default Compose network can usually reach each other freely, so the REST nodes, HAProxy and PostgreSQL may all see one another. Place the database on an internal network that only the REST services join, publish only the HAProxy listener, and verify the result from inside a container with a connection test. Document which ports are published to the host and which stay internal, because host firewall rules and Compose port mappings can disagree.
Pin image versions so updates are deliberate
Compose files that reference latest or a floating tag change behavior whenever the image is pulled again. Pin the Flowable REST image, PostgreSQL and HAProxy to exact versions, record the digests you tested, and make upgrades a planned change with a test run against a copy of your data. Review the release notes for the version you pin, since major Flowable releases change the Java, Spring and Jakarta baseline and may affect the REST application's startup.
Why several REST containers still need one shared database
The HAProxy variant of the Compose stack balances HTTP requests across several Flowable REST containers, but it does not share engine state between them. The engine state lives in the PostgreSQL database: process instances, tasks, variables, jobs and locks. Each container is a full engine node that reads and writes the same schema, so every node must point at the same database. Before you scale the flowable-rest service beyond one container, confirm in the Compose file that each replica receives the same JDBC URL and credentials, and that none of them starts with its own embedded or local database. Confirm also how HAProxy is configured in the project file (health checks, session handling and backend list) by reading that file, since this section does not assume any behavior beyond request distribution.
The reason the shared database matters is the async executor. According to the Flowable advanced documentation, the async executor runs timers and asynchronous jobs from a thread pool and coordinates several nodes through lock owners and lock expiration times stored in the database. When a node takes a job, it records itself as the lock owner with an expiry time. If that node stops before finishing, the lock expires and another node can pick the job up. This recovery only works when all nodes see the same job table. For the same reason, connection pool sizing must account for every node at once: the total number of connections across all containers, plus the async executor threads that hold connections while working, has to fit within what PostgreSQL accepts. Size the pool per container, multiply by replica count, and compare the result against the PostgreSQL connection limit and any pooler in front of it.
A single PostgreSQL instance is therefore the point of failure for the whole cluster, even if every REST container stays healthy. Plan a high availability design for the database before go-live, and test failover with real Flowable traffic rather than assuming it works. A practical test is to start a few process instances with timers, stop the primary, promote the standby or wait for the managed service to fail over, then confirm that timers still fire, that waiting jobs are picked up after lock expiry, and that REST calls succeed once connections are re-established. Ask your database team which failover mechanism applies and how long client reconnection takes in your setup, and record the observed results as evidence for the go-live decision.
What to confirm in your environment before production
A Compose demo proves the containers start and the REST API responds. It does not prove the version, database, high availability, recovery or identity model fit your production environment. Each card below names one item to confirm and who is responsible for confirming it.
Flowable version and Java and Spring baseline
Pin the Flowable version you intend to run, then confirm the Java and Spring baseline it requires. Flowable 7.0.0 moved to Java 17, Spring Boot 3 and Jakarta EE, and Flowable 8.0.0 moved to Spring Boot 4 with no compatibility for Spring Boot 3. Check that your base image, custom delegates and any shared libraries match that baseline. Confirm the choice with the Flowable release notes and your own build team, since a demo image may carry a different stack than the one you will maintain.
Supported PostgreSQL version and JDBC driver
Confirm which PostgreSQL major version and JDBC driver version the Flowable release you chose supports, and whether the Compose file pins a version that your database team accepts. Ask the Flowable project or check the configuration docs for the database list, then test the exact driver against your PostgreSQL build. Your DBA team confirms the server version, extensions and character set settings.
Compose files maintained for your version
Check that the Compose configuration you deploy comes from the release tag matching your Flowable version, not from a branch that moved on. Confirm with the project which Compose files and images it still maintains and which are examples only. Your platform team owns the decision to fork, pin or rebuild them, and records who reviews future changes to the file.
High availability for PostgreSQL
A single PostgreSQL container in Compose is a demo dependency, not a production database. Decide how your organization will provide failover, replication and connection handling, and confirm whether the database team's standard platform covers these needs. Ask the team operating the database how a failover affects running process instances and the async executor's lock handling, since several Flowable nodes depend on one shared database.
Backup and restore testing
Backups only count after a restore has been tested against the same Flowable version and schema. Schedule a restore into a separate environment, then start the REST application and confirm that process definitions, running instances and history load correctly. Your operations team confirms the recovery point and recovery time they can meet, and records the results so auditors can see the test was run.
Identity model and REST authentication
The demo stack ships with default credentials that must be replaced before any user reaches the REST API. Decide whether users come from the built-in identity service, a custom identity service, or LDAP, and confirm how your directory maps to Flowable users and groups. Your security team confirms the authentication mode and credential storage, and the Flowable security documentation explains the defaults to change.
Questions teams ask before running Flowable REST in Compose
Can our team run Flowable REST with the project's Compose files ourselves?
Yes, a team with container experience can start the demo stack from the project's Compose configurations without outside help, because the files are published with the Flowable source. The harder part is moving that stack to production settings: replacing default credentials, pointing the engine at a PostgreSQL instance you operate, setting up backups, and deciding how the stack is updated. Read the Flowable configuration docs before you treat a local run as a production design, and confirm each setting against the version you intend to deploy.
What skills does our staff need for this work?
You need three skill sets in the team: container operations (images, networks, volumes, environment variables and health checks), database administration for PostgreSQL (roles, storage, backups, restores and connection limits), and enough Java knowledge to read the engine's configuration and logs. Someone should also own the decision about which Flowable version to run, since the engine's Java and Spring baseline changes between major releases. If one of these skills is missing, plan training or a partner for that part rather than assuming the Compose file covers it.
How long does a Flowable REST Compose deployment take?
The duration depends on your environment, not on the Compose file itself. The work that usually takes the most time is agreeing on identity and access, the database backup and restore process, network placement, and the change process for updates. Ask any provider, including DeployOpen, for a written scope that lists these items, the environments in scope and the acceptance checks before work starts. Most engagements are fixed-scope, so the agreed scope is what sets the timeline.
What recurring costs should we expect after go-live?
Recurring costs fall into three groups. Infrastructure costs cover the hosts or cloud resources for the engine, the database, storage and load balancer, plus monitoring. PostgreSQL operations cover patching, backup verification, capacity growth and major version upgrades. Flowable upgrades cover testing each new engine release against your process models, because major versions can change the Java, Spring and Jakarta baseline. Ask whether these costs are in your own budget or in a retainer, and whether the quote covers them after handover.
Can we promote the demo stack straight to production?
No, a demo stack should be treated as a starting point. Demo configurations are built to make the first run simple, so they typically use default accounts, local storage and settings that suit testing rather than audit or recovery needs. Before production, replace default credentials, restrict network exposure, configure TLS at the edge, set backup and restore targets, and document how a failed deployment is rolled back. Confirm each of these against the Flowable security and configuration documentation for your chosen version.
Which default credentials must we change before go-live?
Every default account and password in the Compose configuration, including the database account and any application login shipped with the REST application, must be replaced with secrets stored outside the Compose file. Review the authentication mode the REST application uses and confirm it matches your identity model. Record who holds each credential, how it rotates and where it is stored, since auditors often ask for this evidence. Check the Flowable security documentation for the current list rather than relying on memory of an older release.
What should we ask a partner to include in a quote?
Ask for a written scope that names the Flowable version, the database and its version, the topology (single node or the HAProxy load-balanced variant), and the production changes listed above. The quote should also state what is delivered, such as configuration, runbooks, backup and restore tests, and handover sessions, and what the client must provide, such as hosts, DNS, certificates and identity sources. Ask which items recur, how upgrades are handled, and what acceptance tests end the engagement. DeployOpen issues quotes from a written scope rather than a published price list.
How DeployOpen scopes and delivers a Flowable REST deployment
DeployOpen plans, implements, hardens, documents and supports self-hosted Flowable deployments inside your own infrastructure. For Flowable REST on Docker Compose with PostgreSQL, we start from a written scope that covers the containers, database, credentials and production settings your team needs, then deliver it as a fixed-scope engagement.
How we scope
- We confirm which Flowable REST version, engines and REST endpoints your applications need before any configuration starts.
- We record the PostgreSQL version, storage, backup target and network layout that the Compose stack will run against.
- We agree in writing which Compose variant applies, single node or HAProxy load-balanced, and what production settings are in scope.
How we build
- We replace demo defaults, including default credentials, with secrets held in your chosen secrets store and documented rotation steps.
- We configure the PostgreSQL connection, JDBC settings and connection pool sizing, then verify schema creation on a staging stack.
- We test the stack with health checks, REST smoke tests and a failover check for the HAProxy variant where that is in scope.
How we hand over
- We deliver the Compose files, environment configuration, runbooks and a record of every changed default in your repository.
- We document how to upgrade the Flowable image, back up PostgreSQL and restore the stack, using the steps agreed in scope.
- We walk your operations and development teams through the stack and record open items the written scope excluded.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer that follows the agreed scope.
- We can plan the move from the Compose stack to your production orchestration platform as a separately scoped piece of work.
- Ask us to confirm which Flowable release, Java baseline and Spring Boot version your next upgrade will target before it is scheduled.
