When teams install the Flowable REST application on Tomcat
Teams reach for this route when Flowable engines must be callable over HTTP from other systems, and the servers that host them must stay under the organization's control. The Flowable getting started guide lists servlet containers such as Tomcat among the ways to embed Flowable, and the Flowable REST application is the packaged HTTP option. It ships as a WAR file, flowable-rest.war, that you deploy to a servlet container you run yourself. Before planning, confirm that the Tomcat version you operate is 10 or later. Flowable 7.0.0 moved the project to Jakarta EE, so older Tomcat releases that use the javax namespace will not run the application as released.
The WAR covers the BPMN, CMMN, DMN and event registry engines and their REST APIs. It does not include the Flowable UI applications, which the 7.0.0 release notes list as removed, along with the form and content engines and async history. If your plan assumes a browser-based task inbox or admin console from the same deployment, you will need to build that front end yourself or source it from a commercial Flowable product. Confirm which engines and endpoints your integrations need, because that determines the REST surface you will secure and monitor. The version you pick also matters: Flowable 8.0.0 moved to Spring Framework 7 and Spring Boot 4 with no backward compatibility for Spring Boot 3, so check the Flowable 8.0.0 release notes against your Java and Tomcat baseline before you choose a release line.
Choosing H2, MySQL or PostgreSQL for the REST application
H2 is the database type you use to see the REST application run with little setup. It keeps the engine's tables in a file or in memory, so you can deploy flowable-rest.war on Tomcat, call the REST API and deploy a sample process without provisioning a database server. The Flowable configuration docs list H2 among the supported database types, but an evaluation setup is not a production setup. Treat anything you learn on H2 about performance, backup or concurrency as provisional until you repeat it on the database you will run.
- Zero external dependencies: the default configuration needs no JDBC driver download and no separate database host.
- Data is disposable: process instances, history and deployments are lost when the file or memory store is removed, so plan a clean reset.
- Not a sizing reference: lock behavior, connection pooling and history volume on H2 do not predict those values on MySQL or PostgreSQL.
- Single-node assumption: a file-based H2 store is not shared between Tomcat instances, which blocks any clustered test.
- Schema created automatically: the engine creates its tables on first start, which you should not rely on in a production change process.
Before leaving H2, confirm which schema update behavior your version uses and write down the properties you changed, so the production configuration starts from a known list.
PostgreSQL is a common production choice for Flowable because the database type is supported by the engine and it fits the separation most platform teams already run. Moving to PostgreSQL means setting a PostgreSQL JDBC URL, adding the PostgreSQL driver to Tomcat's library path, and giving the application a dedicated database user with rights to create or update the Flowable tables. The exact property names and driver version should come from the configuration docs for your Flowable release, not from older blog posts.
- JDBC change: replace the H2 URL, username and password with a PostgreSQL URL that points at the target database and schema.
- Driver placement: the driver JAR must be available to the servlet container, so confirm where your Tomcat layout expects it.
- Schema ownership: decide whether the application creates tables or a DBA applies DDL scripts before first start.
- Connection pool sizing: size the pool for the async executor and the number of Tomcat threads, not only for web requests.
- Backups and history: history tables grow with use, so plan retention and backup windows before go-live.
Before go-live, run a deployment against an empty PostgreSQL schema and confirm the engine starts cleanly, the tables exist and a test process completes.
MySQL is also a supported production database type. The configuration docs note a precision limit on older versions: MySQL releases below 5.6.4 lack millisecond precision, which matters because Flowable records timestamps for process events, timers and job due dates. If your platform team runs MySQL, confirm the server version before choosing it and check the connector and driver combination against the Flowable release you deploy. The JDBC URL, driver class and character set settings follow MySQL conventions, and they should be set in the externalized configuration rather than inside the WAR.
- Version floor: confirm the server is at or above 5.6.4 so timestamps keep millisecond precision.
- Driver match: use a MySQL JDBC driver version your Flowable release and your server both support.
- Character set and collation: agree these with your DBA before the first schema is created, since changing them later is disruptive.
- Timer and lock behavior: test timers and async job recovery, because lock expiry depends on time values stored in the database.
- Schema handling: choose between automatic creation and DBA-managed DDL in the same way as for PostgreSQL.
Before committing to MySQL, ask your Flowable contact to confirm the supported version range for the release you will use and rerun the timer tests on that version.
Whichever production database you choose, moving off H2 changes three things: the JDBC connection settings, the driver available to Tomcat, and the schema lifecycle. These changes belong in externalized configuration, such as a properties file outside the WAR, so the same artifact can run in test and production. Keeping database credentials out of the deployed archive also keeps them out of the image or artifact your pipeline promotes.
- Connection settings: the URL, driver class, user and password move to external configuration.
- Driver packaging: the driver is a separate JAR, not part of
flowable-rest.war, so it must be added to the servlet container deliberately. - Schema creation: check the property that controls automatic schema updates before the first production start.
- Secrets handling: keep passwords in a secret store or protected file, not in version control.
- Verification: start the application against an empty database and confirm the tables and REST health endpoints respond.
Before the first production start, compare the final configuration file against the H2 version and confirm nothing from the evaluation setup remains.
Configuration options and when each fits
This table compares the main configuration choices for flowable-rest.war on Tomcat: database type, where properties live, authentication mode, and who creates the schema. Read each row for the situation where it fits and the cost it carries, then confirm the exact keys against the Flowable configuration docs for your release.
| Choice | When it fits | Trade-off to weigh | Confirm before choosing |
|---|---|---|---|
| Embedded H2 (default demo setup) | Local evaluation and throwaway test runs on one machine | Data is not durable or shared, so it cannot support several nodes or production history | Confirm the default datasource settings in the configuration docs for your version |
| MySQL or PostgreSQL via JDBC | Production or staging on a database your organization already operates and backs up | You own driver versions, pool sizing, and backups; MySQL below 5.6.4 lacks millisecond precision | Driver class, JDBC URL, and version compatibility for your Flowable release |
| JDBC driver placed in Tomcat lib | Single-server setups where operators manage server-level libraries | Driver upgrades require a Tomcat restart and can conflict with other webapps on the same server | Driver jar location and whether the WAR must bundle it instead |
| Externalized properties file outside the WAR | Production, where the same WAR is promoted across environments with different secrets and endpoints | Operators must manage the file location, permissions, and restarts when values change | Supported external config location and override precedence in the Spring Boot docs |
| Properties packaged inside the WAR | Short-lived test environments with no secret material | Rebuilding the WAR for each environment and storing credentials in the artifact | Whether packaged values are acceptable under your secrets policy |
| Authentication mode set to a built-in or custom identity service | Pilot or internal use with a small set of accounts | Default accounts and password handling must be changed; custom identity services need your own code | Default credentials, password storage, and the identity service override described in the docs |
| Schema created automatically at startup | Development and disposable environments where the app can run DDL | The application user needs DDL rights and schema changes happen without review | Automatic schema update setting and the create and upgrade scripts per database |
| Schema managed by DBA with DDL scripts | Production environments where DDL is applied through change control | Upgrades require running the matching scripts before the new WAR starts | Script set for your database, engine, and history tables in the Flowable docs |
Setting up the REST WAR on Tomcat step by step
This sequence takes a Tomcat host from a clean install to a running Flowable REST application backed by MySQL or PostgreSQL, with configuration kept outside the WAR. Each step closes with a check the team can record, so problems surface at the step that caused them.
Confirm the Java and Tomcat baseline
The platform team installs Tomcat 10 or later, since Flowable 7 uses Jakarta EE and Tomcat 10 and later implement it. They then install a Java runtime that matches the baseline stated in the release notes for the Flowable version being deployed. Flowable 7.0.0 moved to Java 17, so confirm the requirement for the exact release you use. Record the Tomcat and Java versions and the host's time zone and locale settings in the change record. Check:
java -versionreports the expected runtime, and Tomcat starts and serves its default page on the host.Provision the database and application user
A database administrator, or the team that owns the database service, creates an empty database and a dedicated user with the rights Flowable needs to create its tables. MySQL and PostgreSQL are both listed as supported database types in the configuration docs. For MySQL, confirm the server is version 5.6.4 or later, because earlier versions lack millisecond precision. Keep the credentials out of shared scripts and wiki pages. If developers cannot run DDL in production, agree the schema approach with the DBA before the first start. Check: log in as the new user from the Tomcat host, confirm the connection works, and confirm the database is empty.
Add the JDBC driver to Tomcat
Download the JDBC driver for your database from the vendor, choosing a version that the vendor supports for your database server version. Place the jar in Tomcat's shared library directory, typically
$CATALINA_HOME/lib, so the server loads it once for all applications. Do not bundle the driver inside flowable-rest.war, because that ties the driver to one application and complicates later upgrades. Set file ownership so the Tomcat service account can read the jar. Check: the jar is in the directory with the correct permissions, and Tomcat restarts without class-loading or driver errors.Externalize the REST configuration
Create a configuration location outside the Tomcat webapps directory and outside the WAR, owned by the Tomcat service account and readable only by that account. Place the datasource URL, username, password and REST application settings in the configuration file or properties that your release documents, then point the application to it with the mechanism the docs describe. Confirm the file name, property keys and authentication mode setting in the Flowable configuration docs before writing them. Replace any default account or password. Check: the file exists at the configured path, its permissions restrict access, and no credentials appear inside the WAR or in version control.
Deploy flowable-rest.war to Tomcat
Copy flowable-rest.war into Tomcat's webapps directory, or deploy it through the Tomcat manager application if your team uses it. Use the WAR from the release line that matches the engine version you tested, and store a copy of the WAR with its checksum in the change record. Tomcat expands the archive and creates an application context named after the WAR file. Restart Tomcat if your process requires it. Check: the expanded directory appears under webapps, and the Tomcat log shows the application deploying without errors.
Verify the startup logs
Read the Catalina log and the application log from the first start. Flowable creates or validates its tables based on the schema settings in your configuration, so look for schema creation or validation messages and compare them with what the DBA expects. Look for database connection errors, missing driver classes, and warnings about the async executor or default accounts. Confirm the logs do not show repeated restarts or exceptions during engine initialization. Check: the startup completes without exceptions, and the database now contains the Flowable tables. Save the table list so later starts can be compared against it.
Verify the REST call
Send an authenticated request to a read-only endpoint, such as the process definitions list, using the endpoint and authentication mode documented for your release. Use a dedicated test account and keep the administrative account out of routine checks. If your authentication mode requires credentials, confirm that an unauthenticated request is refused. In a non-production environment, deploy one small test process definition through the REST API and confirm it appears in the list. Check: the authenticated call returns HTTP 200 with a JSON body, and the unauthenticated call is rejected.
Securing the REST application before exposing it
The REST application ships with defaults and an engine that trusts its callers, so the work before exposure is mostly configuration and network design. The cards below cover the decisions that connect account handling, authentication, secrets, network reach and transport encryption. Each one points to the security topic for depth rather than repeating it.
Replace default accounts
The REST application's demo setup creates accounts with known credentials, so the first step is to confirm which users exist in the deployed database and remove or disable them. Check the identity configuration in the WAR's properties and any seed data loaded at startup. Confirm that no account used for testing carries over into the production schema, and that the administrative user has a password held outside the repository.
Choose and test the authentication mode
Decide whether the REST application authenticates users against its own identity tables or against an external identity service, and test the chosen mode before go-live. Flowable's identity management can be replaced by overriding the identity service or implementing its interface, with an LDAP reference implementation available. Verify that a request without credentials is rejected, that a valid user sees only the resources granted to them, and that group membership changes take effect.
Protect database credentials and config files
The JDBC username and password for MySQL or PostgreSQL usually sit in properties files that are easy to copy into a repository or image. Move them to environment variables, a secrets manager or a file readable only by the Tomcat service account. Check file permissions on the Tomcat conf directory and the WAR's externalized configuration, and confirm that logs do not print connection strings or request bodies containing credentials.
Restrict network access to the REST endpoints
The REST API should be reachable only from the services and networks that need it, not from the whole corporate segment. Place Tomcat behind a firewall rule or load balancer that allows the approved application servers and administrators, and block direct access to the database port from the web tier. Test the boundary from outside the allowed range and confirm that the Tomcat manager and other default applications are not reachable.
Terminate TLS at the proxy or Tomcat
Credentials and process data travel in every REST call, so transport encryption is required before any external exposure. Decide whether a reverse proxy or load balancer terminates TLS, or whether Tomcat's connector does, and document the choice with the certificate lifecycle that goes with it. If TLS ends at the proxy, confirm the hop from proxy to Tomcat is on a trusted network or is also encrypted, and that forwarded-protocol headers are set correctly.
Authorize in the application, not the engine
The engine does not decide whether a caller may start, complete or read a given process instance. Those checks belong to your application or to a gateway in front of the REST API, so each operation needs an explicit rule. Before exposure, list the REST operations your clients use, map each to the role or ownership rule that governs it, and test that a user cannot act on another user's task by calling the API directly.
What running multiple Tomcat nodes changes
Running more than one Tomcat node against a single Flowable database works because the async executor coordinates through the database itself. Timers and asynchronous jobs are run from a thread pool, and each node claims work by writing a lock owner and a lock expiration time into the job rows. If a node dies or stalls past its lock expiration, another node recovers the expired lock and picks up the job. That means the database is the coordination point, so the database, not the load balancer, decides which node runs a given job. Before you add a second node, confirm the lock and expiration behavior in the Flowable advanced documentation for your version, and confirm that every node points at the same schema with the same settings.
Restarts change in two ways. A Tomcat restart on one node does not stop the process model, but any job that node holds stays locked until its lock expires, so work can pause briefly even though other nodes are healthy. Plan rolling restarts one node at a time, check that the failed job count returns to its baseline, and confirm the drain and shutdown sequence with the Tomcat version your team runs. Keep the expiration interval and the async executor settings identical across nodes, because mismatched values make recovery times unpredictable and are hard to diagnose from logs alone.
Connection pool sizing multiplies. Each node holds its own pool, so the database sees the sum of all pools plus the async executor threads on every node. Size the pool per node against the database connection limit, leaving headroom for administrators, backups and the history tables that grow fastest. Monitor pool wait time, active connections per node, and the count of jobs waiting to run, and alert when they diverge across nodes. Whether session affinity or stateless routing suits the REST API, and how the load balancer should handle long-running requests, are design questions this site does not settle. Confirm them against the engine documentation and your own test results before going to production.
Questions teams ask before installing the REST app on Tomcat
Can our team install the Flowable REST app on Tomcat ourselves?
Yes, if you have engineers who already run Java web applications on Tomcat and who can manage a relational database. The work itself is deploying flowable-rest.war, adding the JDBC driver for your database, and setting externalized properties. The harder parts are the decisions around it: which database and version you run, how users authenticate, how the app is secured and how upgrades will be handled. Teams with no Tomcat or database operations experience usually need to cover those gaps first, either by training or by bringing in a partner. Check your own skills against the list of supported databases in the Flowable configuration docs before deciding.
What drives the effort and cost of a Tomcat installation?
Five factors move the effort most:
- Database: the choice between MySQL, PostgreSQL, Oracle, DB2 and Microsoft SQL Server, and whether your DBA team must create the schema through DDL scripts.
- Authentication: whether users come from a built-in identity store, LDAP or another directory, since identity handling is replaced through the engine's identity service.
- Number of nodes: one Tomcat node is simpler than several sharing one database and async executor, which adds load balancing and lock behavior to test.
- Security review: hardening, default account changes and scripting or XML risk checks that your security team requires.
- Upgrades: the Java, Spring and Jakarta baseline changes between major versions, so the upgrade path affects how the first install is built.
Cost is mostly the people time for these areas. Ask any provider for a quote that lists each factor as a separate line item.
How long does the installation take?
Duration depends on scope, not on the WAR file itself. A single node with one database and a built-in or existing identity source is a narrow task. Adding a DBA-managed schema, LDAP integration, several nodes, a security review and a documented upgrade procedure widens it considerably. Ask for a timeline that tracks each of those items, with the dependencies and the people you must provide, so you can see where delays would come from. A fixed-scope agreement fixes deliverables and dates in writing before work starts, which makes the timeline easier to check against what you asked for.
What must our team provide before the installation starts?
Plan to provide four things:
- Database: a running server of a supported type and version, with a database and user created for Flowable, and backups in place.
- Tomcat hosts: servers or containers with a Tomcat version compatible with the Flowable release you choose, plus network access to the database and identity source.
- Identity source: the directory or user list the REST app will authenticate against, with the group or role model that Flowable users need.
- Test data: sample process, case or decision models, and test users, so the install can be verified against your real workflows.
Confirm the exact Tomcat and JDBC driver versions with your chosen Flowable release notes before you order hosts or licenses.
Can we keep H2 in production?
H2 is the default database in the Flowable examples, and it is useful for trials and development. For production, the engine docs list MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server as supported database types, and the switch is a configuration change to the datasource and driver. Running production on an embedded file database makes backup, concurrency across nodes and recovery harder to control. Treat H2 as a development choice and plan the move to a server database before any users depend on the system. If you use MySQL, check the minimum version the docs note for millisecond precision.
What should we check in the Flowable release before choosing a version?
Start with the release notes for the version you plan to run. Major versions change the platform baseline. Flowable 7.0.0 moved to Java 17, Spring Boot 3 and Jakarta EE, and Flowable 8.0.0 moved to Spring Framework 7 and Spring Boot 4 without backward compatibility for Spring Boot 3. Those changes affect which Tomcat and Java versions you can use and whether your team needs to rebuild any custom code. Confirm the compatibility matrix with Flowable and your own environment before buying hosts or writing the deployment plan.
How do we get a fixed-scope quote for this work?
Send a written scope that names the Flowable version, Tomcat version, database and version, number of nodes, identity source, authentication mode, security review expectations, upgrade requirements and the environments to build (development, test and production). Include what you will provide from the list above. Ask for deliverables, acceptance criteria, responsibilities on each side and a timeline in the quote. DeployOpen works from a written scope and agrees deliverables, scope and timelines in writing before work starts, so a clear scope document gives you a comparable quote from any provider.
How DeployOpen scopes a Tomcat REST installation
A Tomcat installation of the Flowable REST application is scoped in writing before any work starts. The scope document, not the first deployment, sets what gets delivered. The engagement opens with an environment inventory: the Tomcat version and its Java runtime, the database engine and version the client has chosen, the JDBC driver approach, the network path between the Tomcat hosts and the database, the reverse proxy or load balancer in front of the application, and the identity source the REST API will authenticate against. Each item is confirmed against the client's own standards before any configuration is written, so the scope reflects what the organization actually runs.
The decisions that shape the rest of the work are made during scoping. These include which relational database the engine will use, whether schema creation is performed by the application or by a DBA using scripts, how externalized configuration will be supplied to the Tomcat instances, and which authentication mode the REST application will run in. The configuration design then covers the properties file layout, secrets handling, and the settings that differ between test and production. Deployment, verification and handover documentation follow as defined deliverables. DeployOpen performs this work inside the client's own cloud accounts, data centers or air-gapped networks, so the client keeps control of the hosts, credentials and data throughout.
Ask for the written scope to list each deliverable, the environments in which it is verified, the parties responsible for database administration and identity, and the handover artifacts the client will keep. Confirm with your own change process how deployments are approved. Where the platform needs to keep running after handover, ongoing support, upgrades and testing are available as a retainer, which can be agreed alongside the fixed-scope work.
How DeployOpen delivers Flowable REST on Tomcat
DeployOpen plans, builds, documents and supports the Flowable REST application inside your own infrastructure, including the Tomcat host, database connection, externalized configuration and authentication mode. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts.
How we scope
- Confirm the Tomcat version, Java runtime and Flowable release line before choosing the WAR build.
- Record the target database, JDBC driver source, schema ownership and whether developers may run DDL.
- Define the authentication mode, identity source and which REST endpoints and users must be reachable.
How we build
- Deploy flowable-rest.war to a non-production Tomcat, switch the datasource from H2 and load the JDBC driver.
- Move database credentials, REST app properties and logging settings into externalized configuration outside the WAR.
- Test engine startup, schema creation, process deployment and REST calls against the chosen authentication mode.
How we hand over
- Deliver a written runbook covering the Tomcat layout, configuration keys, file locations and restart steps.
- Document the database setup, change-control steps for driver and property updates, and the verification checklist used.
- Walk your platform and operations staff through the build so they can repeat deployments without DeployOpen.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer alongside the fixed-scope build.
- Plan Flowable and Tomcat upgrades against the release notes before each change, including Java and Spring baseline changes.
- Agree the support boundary, response expectations and reporting in the written scope so ownership stays clear.
