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.

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 Control	repo.flowable.com/docker/flowable/flowable-control

The docker images can be customized with additional JARs by extending them or mounting a volume into the directory /additional-classpath/.

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-control:
    image: repo.flowable.com/docker/flowable/flowable-control:latest
    environment:
      flowable.common.app.idm-admin.user: admin
      flowable.common.app.idm-admin.password: test
      flowable.control.app.cluster-config.server-address: http://flowable-work
      flowable.control.app.cluster-config.port: 8080
      flowable.control.app.cluster-config.context-root: /
      flowable.control.app.cluster-config.password: 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.

Docker Images with Mac OS X and a M4 processor

When using Mac OS X with a M4 the start of Java based packages will fail with the following 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 the following environment variable can be added for Flowable Design, Work, and Control:

JAVA_OPTS: "-XX:UseSVE=0"

For Elasticsearch the following environment variable can be added:

_JAVA_OPTIONS: "-XX:UseSVE=0"

Using an Angular-based Flowable Design

For Flowable Design until version 3.13 and the 3.14 Angular-based Flowable Design the properties are different:

flowable.common.app.idm-admin.user: admin
flowable.common.app.idm-admin.password: test
flowable.common.app.idm-url: http://flowable-work:8080
flowable.modeler.app.deployment-api-url: http://flowable-work:8080/app-api
flowable.modeler.app.undeployment-api-url: http://flowable-work:8080/platform-api/app-deployments
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

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

• Flowable Work Properties
• Flowable Design Properties
• Flowable Control Properties

Start Flowable

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

docker compose up -d

To start the applications.

To 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 Control	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 Control. The file can be mounted as a volume into the container.