Setup

System Requirements

Before proceeding with installation, ensure your system meets the following minimum requirements:

Operating System: 64-bit Windows, Linux, or macOS
RAM: Minimum 8 GB (16 GB recommended)
Disk Space: Minimum 10 GB of free space
Java: JDK or JRE version 21

Verify your Java installation by running:

java -version

Installation Methods

Portable Distribution

The portable distribution allows you to run Flowset Control without additional dependencies (except Java). It ships as a self-contained application JAR and runs on an embedded HSQLDB database, created automatically on first startup — no external database is required. Ideal for quick testing or local development.

Get the latest Flowset Control distribution package from the official downloads page.

Download

Prerequisites:

Component	Requirement
Java	JDK or JRE 17 (Java 21 also supported)
OS	Linux, macOS, or Windows
Port 8081	Must be free (configurable, see below)
RAM	At least 512 MB available for the JVM

Component

Requirement

Java

JDK or JRE 17 (Java 21 also supported)

Linux, macOS, or Windows

Port 8081

Must be free (configurable, see below)

RAM

At least 512 MB available for the JVM

The archive has the following structure:

flowset-control-community/
├── flowset-control-community-2026.0.1-rc.jar   # compiled application JAR
├── run.sh  / run.bat                           # start the application
├── stop.sh / stop.bat                          # stop the application
├── data/                                       # HSQLDB data (created automatically)
└── README.md

Running Instructions:

Get the portable archive from the official downloads page.
Unpack the archive into any working directory. Keep the folder structure intact — the run/stop scripts must stay next to the application JAR.
Start the application:

Linux/macOS:
```
chmod +x run.sh
./run.sh
```
Windows:
```
run.bat
```
On startup the script verifies Java, launches the application, and automatically opens the browser once it is ready.
Access the application at: http://localhost:8081.

Default credentials: admin/admin. Change the default password immediately after the first login.

Stopping the application:

Linux/macOS:

./stop.sh

Windows:

stop.bat

Changing the HTTP port:

If port 8081 is already in use, pass a different port when starting:

./run.sh --server.port=8090

run.bat --server.port=8090

The embedded HSQLDB stores its files under the data/ folder next to the JAR. It is intended for evaluation and local development. For production, use the external database configuration with Oracle or PostgreSQL.

Docker Compose

This method allows for quick startup of Flowset Control in containers, without manual database or environment configuration.

Prerequisites:

Docker and Docker Compose
Verify installations:
```
docker --version
docker compose version
```

Running Instructions:

Create a docker-compose.yml file with:

version: '3.8'

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: flowset-control
      POSTGRES_USER: root
      POSTGRES_PASSWORD: root
    ports:
      - "5432:5432"

  flowset-control:
    image: flowset/flowset-control-community:latest
    environment:
      MAIN_DATASOURCE_URL: jdbc:postgresql://postgres:5432/flowset-control
      MAIN_DATASOURCE_USERNAME: root
      MAIN_DATASOURCE_PASSWORD: root
      SERVER_PORT: 8081
    ports:
      - "8081:8081"
    depends_on:
      - postgres

Start the containers:
```
docker compose up -d
```
Access the application at: http://localhost:8081.
To stop the containers:
```
docker compose down
```

Detailed instructions are available at GitHub.

Source Code Build

Build and run from source for development or custom deployments.

Prerequisites:

Git
Java 21 JDK
PostgreSQL database

Running Instructions:

Clone the repository:

git clone https://github.com/flowset/flowset-control-community

Configure PostgreSQL database.

Flowset Control stores data, such as BPM engine connections, in a database. By default, Flowset Control requires a PostgreSQL database with the following parameters:
- Database name: flowset-control
- Username: root
- Password: root
Navigate to the project directory and run:
```
./gradlew bootRun
```
Access the application at: http://localhost:8081.

WildFly Bundle

A self-contained archive that already includes the WildFly application server with Flowset Control deployed and pre-configured. No separate WildFly download or manual deployment is required. By default the application runs on an embedded HSQLDB database, created automatically on first startup, so no external database is needed to get started.

Prerequisites:

Component	Requirement
Java	JDK or JRE 17 (Java 21 also supported)
OS	Linux, macOS, or Windows
Port 8080	Must be free (configurable, see below)
RAM	At least 2 GB available for the JVM

Component

Requirement

Java

JDK or JRE 17 (Java 21 also supported)

Linux, macOS, or Windows

Port 8080

Must be free (configurable, see below)

RAM

At least 2 GB available for the JVM

The archive has the following structure:

flowset-control-community-wildfly-2026.0.1/
├── server.tar.gz                         # WildFly + deployed app (unpacked on first start)
├── start.sh / start.bat                  # start the server
├── stop.sh  / stop.bat                   # stop the server gracefully
└── README.md

On the first start, server.tar.gz is unpacked automatically into a server/wildfly/ folder next to the scripts (a one-time step of a few seconds):

flowset-control-community-wildfly-2026.0.1/
└── server/wildfly/                       # WildFly application server
    ├── bin/standalone.conf               # pre-configured for Flowset Control
    └── standalone/deployments/
        └── flowset-control-community-2026.0.1.war   # already deployed

The server is shipped as an inner server.tar.gz so the outer archive contains only short paths. This lets it open with the built-in extractor on Windows and macOS without hitting the Windows 260-character path limit. Unpacking uses tar (built into Windows 10 1803+, Windows 11, macOS and Linux), which has no such limit.

Running Instructions:

Get the WildFly bundle from the official downloads page.
Unpack the archive into any working directory. Keep the folder structure intact — the start/stop scripts must stay next to server.tar.gz. On Windows the built-in Explorer extractor works fine here, because the archive contains only short paths.
Start the server (on the first launch the bundled server is unpacked automatically):

Linux/macOS:
```
chmod +x start.sh
./start.sh
```
Windows:
```
start.bat
```
Startup takes approximately 40–60 seconds. A successful start ends with a line like WildFly 40.0.0.Final started in 43443ms.
Access the application at: http://localhost:8080.

Default credentials: admin/admin. Change the default password immediately after the first login.

Stopping the server:

Linux/macOS:

./stop.sh

Windows:

stop.bat

Changing the HTTP port:

If port 8080 is already in use, pass a different port when starting:

./start.sh -Djboss.http.port=8090

start.bat -Djboss.http.port=8090

Health check:

curl http://localhost:8080/actuator/health
# Expected: {"status":"UP"}

Log files:

server/wildfly/standalone/log/server.log

Updating to a new version:

Replace the WAR in the deployments folder while WildFly is running — it reloads automatically:

cp flowset-control-community-2026.0.1.war \
   server/wildfly/standalone/deployments/

The embedded HSQLDB is intended for evaluation and small installations. For production, point the application at an external database by editing server/wildfly/bin/standalone.conf — uncomment the Oracle or PostgreSQL main.datasource. block and set the URL, username and password (or provide them via the FLOWSET_DB_URL / FLOWSET_DB_USER / FLOWSET_DB_PASS environment variables). Supported: *Oracle 19c+ and PostgreSQL. Restart the server after changing the configuration.

Post-Installation

After successful installation:

Open your web browser and navigate to http://localhost:8081.
Use default administrator credentials (admin/admin).
Configure your BPM engine connections.