Installation with Docker

The document describes a simple setup with Docker to get started with Flowable.

Important

This setup is not intended to be used in production or for load testing. Please refer to the cloud deployment for a production setup.

info

This documentation refers to the Docker setup with Flowable Hub, which is provided starting with version 2026.1. If you are looking for the Docker setup with Flowable Control, which is available until version 2026.1, you can navigate there with this link Installation with Docker (Flowable Control).

Prerequisites

Docker needs to be installed on your machine to use this guide. If using Docker is not an option, please check out the detailed installation guide without Docker.

As a first step it is required to authenticate to the Flowable Artifactory which is hosting the Docker images. This can be done either with your Flowable credentials or your account and an API key. To use an API key: go to Flowable Artifacts and select at the top right Welcome ..., then Edit Profile. Unlock the settings with your password and generate a new API key.

tip

In case you do not have credentials yet, please reach out to your contact person at Flowable (e.g. Account Executive). Alternatively, you can also try out Flowable without docker with the enterprise trial.

Once you have your credentials, open a terminal and execute:

docker login repo.flowable.com

This will prompt you for your username and password. After a successful login (using the API key instead of the password if you chose that option) you will see that the authentication was successful:

docker login repo.flowable.com
Username: <your-username>
Password:
Login Succeeded

Docker Images

Flowable offers the following out-of-the-box docker images:

Application	Docker Image
Flowable Work	repo.flowable.com/docker/flowable/flowable-work
Flowable Work with chat	repo.flowable.com/docker/flowable/flowable-engage
Flowable Design	repo.flowable.com/docker/flowable/flowable-design
Flowable Hub	repo.flowable.com/docker/flowable/flowable-hub

The docker images can be customized with additional JARs by extending them or mounting a volume into the directory /additional-classpath/. See Injecting Custom Java Libraries for details.

Docker Compose File

To start the Flowable applications you can use Docker compose. This allows you to define all the containers and dependencies to start the containers.

The following docker-compose.yml file uses the latest Flowable version with a postgres database and Elasticsearch:

services:
  database:
    image: postgres:14.2
    environment:
      POSTGRES_DB: flowable
      POSTGRES_USER: flowable
      POSTGRES_PASSWORD: flowable
    volumes:
      - data_db:/var/lib/postgresql/data

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.17.3
    environment:
      discovery.type: single-node
      node.name: flowable-node-01
      cluster.name: flowable-cluster
      xpack.security.enabled: "false"
    volumes:
      - data_es:/usr/share/elasticsearch/data
    ulimits:
      memlock:
        soft: -1
        hard: -1

  flowable-work:
    image: repo.flowable.com/docker/flowable/flowable-work:latest
    environment:
      flowable.content.storage.root-folder: /content-storage
      server.servlet.context-path: /
      spring.elasticsearch.uris: http://elasticsearch:9200
      spring.datasource.driver-class-name: org.postgresql.Driver
      spring.datasource.url: jdbc:postgresql://database:5432/flowable
      spring.datasource.username: flowable
      spring.datasource.password: flowable
    ports:
      - 8090:8080
    volumes:
      - data_work:/content-storage
    depends_on:
      - database
      - elasticsearch
    user: root
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

  flowable-design:
    image: repo.flowable.com/docker/flowable/flowable-design:latest
    environment:
      flowable.design.remote.authentication.user: admin
      flowable.design.remote.authentication.password: test
      flowable.design.remote.idm-url: http://flowable-work:8080
      flowable.design.deployment-api-url: http://flowable-work:8080/app-api
      flowable.design.undeployment-api-url: http://flowable-work:8080/platform-api/app-deployments
      flowable.design.db-store-enabled: "true"
      server.servlet.context-path: /
      spring.datasource.driver-class-name: org.postgresql.Driver
      spring.datasource.url: jdbc:postgresql://database:5432/flowable
      spring.datasource.username: flowable
      spring.datasource.password: flowable
    ports:
      - 8091:8080
    depends_on:
      - database

  flowable-hub:
    image: repo.flowable.com/docker/flowable/flowable-hub:latest
    environment:
      flowable.hub.db-store-enabled: "true"
      flowable.hub.app-provider.type: properties
      flowable.hub.apps.work.name: Flowable Work
      flowable.hub.apps.work.public-url: http://localhost:8090
      flowable.hub.apps.work.private-url: http://flowable-work:8080
      flowable.hub.apps.work.authentication-type: basic
      flowable.hub.apps.work.credential-key: admin
      flowable.hub.apps.work.credential-value: test
      server.servlet.context-path: /
      spring.datasource.driver-class-name: org.postgresql.Driver
      spring.datasource.url: jdbc:postgresql://database:5432/flowable
      spring.datasource.username: flowable
      spring.datasource.password: flowable
    ports:
      - 8092:8080
    depends_on:
      - database

volumes:
  data_db:
  data_es:
  data_work:

You can replace the latest version tag of Flowable with a specific version number of Flowable.

In case you are using a Mac with an M4 processor, please check the troubleshooting section below.

A list of properties to configure the applications can be found on the following pages:

• Flowable Work Properties
• Flowable Design Properties
• Flowable Hub Properties

Start Flowable

Once you created the docker-compose.yml file you can execute:

docker compose up -d

To start the applications.

The applications can be stopped with docker compose down. This will still keep the network and persisted volumes, to remove those as well you can use docker compose down -v.

Once everything is started you can access the following applications:

Name	URL	Username	Password
Flowable Design	http://localhost:8091	admin	test
Flowable Work	http://localhost:8090	admin	test
Flowable Hub	http://localhost:8092	admin	test

note

The docker images do not contain a license file. To upload the license you can sign in to Flowable Design. Flowable Design will ask you to upload the license directly after the successful login.

In case you would like to add the license file automatically, you can disable the database storage. Please refer to the documentation for Flowable Work, Flowable Design, and Flowable Hub. The file can be mounted as a volume into the container.

Connect Flowable Hub to Flowable Work

The docker-compose.yml file above connects Flowable Hub to Flowable Work with the App properties:

• flowable.hub.app-provider.type: properties tells Hub to read the runtime environments (called clusters) from the properties instead of the database.
• flowable.hub.apps.work.* defines a cluster with the id work. Hub calls Flowable Work on the private-url inside the Docker network, while the public-url is the address used by the browser. Hub authenticates with basic authentication using the Flowable Work admin user.

After signing in to Flowable Hub, click Go to environment to open the Flowable Work cluster. In case there are multiple environments configured, the environment can be selected with the environment selector in the top-left corner.

note

With flowable.hub.app-provider.type: properties the clusters cannot be changed in the Hub UI. To manage the clusters in the UI under Hub Configuration → Clusters instead, remove the flowable.hub.app-provider.type and flowable.hub.apps.* properties. See the Clusters documentation for details.

Troubleshooting

Mac with an M4 processor

When using a Mac with an M4 processor, the Java based containers fail to start with a SIGILL error.

Error message

#
# A fatal error has been detected by the Java Runtime Environment:
#
#  SIGILL (0x4) at pc=0x0000ffffab267c5c, pid=1, tid=7
#
# JRE version:  (21.0.5+11) (build )
# Java VM: OpenJDK 64-Bit Server VM (21.0.5+11-LTS, mixed mode, sharing, tiered, compressed oops, compressed class ptrs, g1 gc, linux-aarch64)
# Problematic frame:
# j  java.lang.System.registerNatives()V+0 java.base@21.0.5

As a workaround, add the following environment variable to the flowable-work, flowable-design, and flowable-hub services in the docker-compose.yml file:

    environment:
      JAVA_OPTS: "-XX:UseSVE=0"

For the elasticsearch service, add the following environment variable:

    environment:
      _JAVA_OPTIONS: "-XX:UseSVE=0"