Skip to main content

Flowable Hub Installation Instructions

2026.1.0+

Flowable Hub is the administration and monitoring application for Flowable. It connects to one or more Flowable runtime environments (each called a cluster) and gives you full visibility and control over what runs there. Hub is a Spring Boot application and is configured in the same way as the other Flowable applications, using an application.properties file and the flowable.hub.* / application.hub.* property namespaces.

Prerequisites​

See the Flowable System Requirements and Supported Software documentation.

Flowable Hub requires a valid license that includes the Flowable Hub entitlement.

Step-by-step Installation​

License File​

Flowable requires that you have a valid license for the product. The license is either stored on the file system or in the database. If the license is provided as a file then it is typically located in the .flowable folder of your home directory. On Unix or macOS the file is ~/.flowable/flowable.license. The location of the license file can be changed in the application.properties file (see below).

flowable.hub.license-location=file:/myCustomLocation/flowable.license

To store the license in the database then the following property must be set in the application.properties file:

flowable.hub.db-store-enabled=true

With the license database store mode enabled a license is uploaded using the Flowable Hub application, from Hub Configuration → License using the Upload license action. See the License User Documentation for details.

note

This license is for the Flowable Hub application itself. It is separate from the license usage of a connected runtime environment — to check whether a runtime stays within its licensed usage (named and occasional users, root instances and agents), open System Info → License Info for that environment in Hub.

WAR File​

The Flowable Hub WAR file can be either

If you do not already have access to the Flowable Artifactory and the required dependencies, please contact your Flowable representative.

Copy the file into the Tomcat webapps folder. When deployed to Tomcat, the WAR file name determines the context path, so a file named flowable-hub.war is served under /flowable-hub.

Running Flowable Hub in Tomcat​

You can download Tomcat from here. Once you download the package you should unpack it. The Tomcat is started by running bin/catalina.sh (bin/catalina.bat on Windows). Do not run Tomcat yet; first follow the steps for installing the Flowable WAR file.

Application Configuration File​

Copy the file named application.properties into the Tomcat lib folder.

This file contains the most common configurations, such as the data source. By default, an H2 database is created in the ~/flowable-db folder (in a hub database).

If you want to run with a different database, or use H2 in a different location, follow the instructions in the Using a Different Database section of this guide.

Flowable Hub Administration User​

Out of the box Flowable Hub creates one administration user with the username admin and password test in the default tenant. This user is placed in the flowableAdministrator group and granted the Hub Admin role, which gives full access to Hub and to Hub Configuration.

The password can be customized (only during first startup of Flowable Hub, i.e. when the database is empty) by setting the following property:

flowable.hub.bootstrap.default-admin.password=<your custom password>

To disable the automatic creation of the default admin user altogether — for example when all identities come from an external identity provider — set:

flowable.hub.bootstrap.default-admin.enabled=false
caution

Make sure to change the default password before exposing Flowable Hub outside of a local development environment.

Limit access based on groups or authorities​

Sometimes you do not want all users to be able to access Flowable Hub. Out of the box, you can configure that with two properties.

application.hub.security.access-groups and application.hub.security.access-authorities

Both properties act as an allow list to only grant access to users with a specific group or authority.

note

In order to allow easy usage of those properties, it is not required to add the GROUP_ prefix for groups. application.hub.security.access-groups=flowableUserGroup is enough.

OAuth2​

The out-of-the-box Flowable Hub application uses HTTP Basic authentication by default. To use an OAuth2 / OpenID Connect provider instead, switch the security type:

application.hub.security.type=oauth2

The client registration itself is configured in the standard Spring Boot way, using the spring.security.oauth2.client.* properties. There are different OAuth2 providers; please refer to the Keycloak OAuth2 how-to for a configuration sample.

When required, the post-logout behaviour can be tuned with flowable.hub.security.oauth2.post-logout-redirect-url and flowable.hub.security.oauth2.end-session-endpoint-url.

Refresh Token​

When using OAuth2 the offline_access scope can be used for the client registration. This enables Flowable Hub to refresh the access token when it expires, e.g. when using oauth2CurrentUser to communicate with a connected runtime environment.

For this purpose there is the property application.hub.security.oauth2.authorized-client-repository-type with a default value of session. With this the refresh token is stored in the HTTP session and can be used to refresh the access token when it expires. If you are running a single node then this can be changed to default, which will use an in-memory implementation.

Security and encryption secrets​

For any non-development installation, set the following secrets in application.properties:

# Encrypts sensitive values (such as OAuth2 SSO client secrets) before they are stored in the database.
# Both values must be exactly 16 ASCII characters.
flowable.hub.encryption.secret=<16 character secret>
flowable.hub.encryption.initialization-vector=<16 character iv>

# Signing secret used for token-based request authentication. Must be at least 32 characters if set.
flowable.hub.token-signing-secret=<at least 32 characters>
caution

Do not change the encryption secret or initialization-vector after client secrets have been saved: existing secrets can no longer be decrypted and would need to be reconfigured.

Starting Tomcat​

You can now start Tomcat by running bin/catalina.sh (bin/catalina.bat on Windows). Alternatively, you can run bin/catalina.sh run to have it in the foreground.

You should now be able to access the Flowable Hub application:

You can log in with the user admin and password test. You need to login in every application as the Flowable applications use different user stores by default.

Connecting to a Runtime Environment​

Unlike the other Flowable applications, Flowable Hub is not configured with a fixed runtime connection through properties. Instead, after logging in for the first time you register the runtime environments — called clusters — that Hub should monitor and manage.

Open Hub Configuration → Clusters and choose Create new. For each cluster you describe both how to reach it (public and private address, and an authentication type such as Basic, Bearer, OAuth2 or Current User) and what it is (whether it is a multi-tenant environment, Flowable Work and/or Flowable Engage, whether Elasticsearch is enabled, and so on). Use Test to verify the connection before saving.

Each registered cluster then becomes an environment you can select from the environment selector in the top-left corner. For the full details see the Clusters User Documentation.

Using a Different Database​

The Flowable applications are Spring Boot applications and are configured in a standard Spring Boot way. This means that the database can be configured by setting the following properties to the application.properties file previously mentioned.

spring.datasource.url=<jdbc URL>
spring.datasource.driver-class-name=<jdbc driver class name>
spring.datasource.username=<username>
spring.datasource.password=<password>

The application.properties file contains examples for the compatible databases:

  • H2

  • MySQL

  • MariaDB

  • PostgreSQL

  • Oracle

  • Microsoft SQL Server

  • DB2

The Flowable applications do not ship with the JDBC drivers for databases other than H2. Therefore you need to download the appropriate JDBC driver and copy the jar into the Tomcat lib folder.

The Flowable applications create the required database and tables when they start. The database user (normally, flowable) needs database schema read-write permissions.

It is also possible to disable the schema creation or only perform schema validation. For this the property flowable.hub.database-schema-update needs to be set.

The possible values for it are:

  • true - Default value. A check is performed, and an update of the schema is performed if it is necessary.
  • false - Checks the version of the DB schema against the library and throws an exception if the versions don't match.
  • ignore - Does nothing. No schema creation, no schema version check.

Running Multiple Nodes​

Flowable Hub can be run with more than one node behind a load balancer. When doing so — and especially when using OAuth2 without sticky sessions — the HTTP session needs to be shared between the nodes. Flowable Hub supports sharing the session over Redis using Spring Session.

To enable it, set the following properties:

application.hub.redis-enabled=true
spring.data.redis.host=localhost
spring.data.redis.port=6379
spring.data.redis.password=
#spring.data.redis.ssl.enabled=true
note

Managed Redis services (such as Azure Cache for Redis or AWS ElastiCache) deny the CONFIG command that Spring Session issues at startup. On those services add spring.session.redis.configure-action=none.

Development Environment Setup​

This section is relevant when you want to build your own version of Flowable Hub, instead of using the out of the box application.

Flowable Hub is based on Spring Boot and therefore requires the compatible version of it as a base for any development environment. The easiest way to setup a Flowable development project is to first generate a Spring Boot Project by using the Spring Initializr.

You can import the generated project into the IDE of your choice (like IntelliJ IDEA or Eclipse).

Flowable Hub Dependencies​

Flowable Hub utilizes a Maven starter to pull in the required Flowable services and the Hub frontend. Add the following dependency as a child of the existing <dependencies> tag of the pom.xml file to set up Flowable Hub:

<dependency>
    <groupId>com.flowable.hub</groupId>
    <artifactId>flowable-spring-boot-starter-hub</artifactId>
    <version>${com.flowable.hub.version}</version>
</dependency>

The maven property com.flowable.hub.version can be configured to the Flowable Hub version.