Standalone installation

Install Bonita Process Designer from the standalone archive, without Docker, on a Java 17 runtime and against an external PostgreSQL database.

The standalone distribution is for hosts where Docker is not an option. It is a single portable Java application that serves both the REST API and the editor UI on one port.

For the Docker-based alternative, see Install with Docker.

What the archive contains

The archive is architecture-independent — the same file runs on Linux, Windows and macOS. It contains:

  • app.jar — the application: the REST API and the editor UI in one artifact;

  • start.sh and start.bat — start wrappers that read your configuration and launch the application;

  • config.env.example — the configuration template you copy and edit;

  • STANDALONE.md — a short reference for this distribution;

  • docs/ — the offline product documentation bundled with the release. It is a separate documentation set, built with the product, and not a copy of this site;

  • tools/ — in official builds, the license request-key generator, used to produce the host fingerprint that Ofelia needs in order to issue your license file. See Manage the license.

At the first start, the application also creates a licenses/ folder next to app.jar, where it keeps the license file, and a logs/ folder for its log file.

Prerequisites

  • A Java 17 or newer runtime on the host. The archive does not bundle one.

  • An externally-managed PostgreSQL 16+ instance reachable from the host, with a database and credentials reserved for the application.

  • Network access from the host to that database.

  • Outbound internet access to register the installation and to use AI generation (a proxy without authentication is supported — see HTTP_PROXY in Configuration reference). License validation needs no network access.

The standalone distribution includes neither a database nor a Java runtime. If you have neither available, use Install with Docker instead — it provisions both for you.

The start wrapper locates Java through JRE_HOME, then JAVA_HOME, then java on the PATH, and stops with a clear error if it finds none or if the version is older than 17.

Install

1. Download and extract the archive

Download the archive from the Customer Service Center. One archive covers every platform, published in two equivalent formats — pick whichever your host handles more easily.

tar xzf process-designer-<version>-standalone.tar.gz
cd process-designer-<version>-standalone

On Windows, extract process-designer-<version>-standalone.zip with File Explorer or tar -xf.

2. Configure

Copy the template and edit it:

cp config.env.example config.env

Set at least the three required variables in config.env:

# Required
DATABASE_URL=jdbc:postgresql://<host>:<port>/<database>
SPRING_DATASOURCE_USERNAME=<database-user>
SPRING_DATASOURCE_PASSWORD=<database-password>

# Recommended: the address users type in the browser
CORS_ORIGIN=http://<server-address>:8080

# Optional
# HTTP port serving both the editor UI and the API (default 8080)
PORT=8080
# Set to true behind a TLS-terminating reverse proxy
USE_HTTPS=false
# Raise to DEBUG when diagnosing a problem
LOG_LEVEL=INFO
# JVM options, heap ceiling first
JAVA_OPTS=-Xmx512m

A single process serves the editor UI and the REST API on PORT. There is no separate back-end port: BACKEND_PORT is not read.

Keep each comment on a line of its own, as above: on Windows, start.bat reads everything after the = sign as the value, including a trailing comment. Set CORS_ORIGIN to the exact address users type in the browser, or to the HTTPS origin of your reverse proxy: see CORS security.

DATABASE_URL must use the JDBC format and start with jdbc:postgresql://. A libpq-style URL such as postgresql://user:pass@host/db is rejected — keep the URL credential-free and put the user and password in SPRING_DATASOURCE_USERNAME and SPRING_DATASOURCE_PASSWORD.

The license file is kept in ./licenses, next to app.jar, unless you set BONITA_LICENSE_FOLDER. For the full list of configurable variables — ports, TLS, proxy, CORS, retention, logging — see Configuration reference.

3. Start

On Linux and macOS:

./start.sh

On Windows, in Windows PowerShell:

.\start.bat

In cmd.exe, type start.bat.

The start wrapper validates config.env — exiting with a clear error that names any missing required variable — resolves a Java 17+ runtime, then launches the application in the foreground. Database migrations run automatically at startup: there is no separate migration step, and the schema is created on first run, which makes the first start take up to a minute longer.

Open http://localhost:8080 in a browser. The first login uses the default admin / admin account; you are then prompted to change the password. Continue with First-time setup.

4. Stop

Press Ctrl+C in the terminal running the start script. There is a single process, so that stops the whole application.

On Windows, if the Java process is left running — for example because the console window was closed rather than interrupted — end it from the Task Manager. The taskkill /im java.exe command also works, but it terminates every Java process on the host, so check what else is running first.

Logs

The application logs to the console where you started it and to a rotating file, with nothing to configure:

logs/process-designer.log

The start script prints the path when it launches. The file rolls over at 10 MB and once a day, keeps 30 days of gzipped archives, and stays around 1 GB in total — so it needs no logrotate setup.

Size the partition for about 1 GB, not exactly 1 GB: the total-size cap is enforced at each rollover, so the directory can briefly hold roughly one archive more than the limit. Treat 1 GB as the bound to provision for rather than a hard ceiling, and see Rotation and retention for the limits and how to change them.

Do not also redirect the console output into that directory (./start.sh > logs/app.log). The result is a second copy of every line in a file that never rotates, which defeats the limits above.

To collect the log for a support request, send logs/ as a whole. For log levels, what a log line contains, and how to trace a single request, see Logs and log levels.

Run as a service (Linux)

The archive does not ship service definitions. A minimal systemd unit looks like this:

[Unit]
Description=Bonita Process Designer
After=network.target postgresql.service

[Service]
Type=simple
WorkingDirectory=/opt/process-designer-1.1.0-standalone
ExecStart=/opt/process-designer-1.1.0-standalone/start.sh
Restart=on-failure

[Install]
WantedBy=multi-user.target

Replace /opt/process-designer-1.1.0-standalone with the folder you extracted. If Java is not on the default PATH, add Environment=JAVA_HOME=<java-home> to the [Service] section. Under systemd the console output goes to the journal. Read it with journalctl -u process-designer, and see Logs and log levels for retention.

Upgrade

To upgrade an existing installation, extract the new archive into a new directory and carry over config.env and licenses/: see Upgrade the standalone distribution.

Troubleshooting

config.env not found / missing required variable

Copy config.env.example to config.env and fill in the three required variables.

DATABASE_URL must use the JDBC format

The URL must start with jdbc:postgresql://. Move any credentials out of the URL and into SPRING_DATASOURCE_USERNAME / SPRING_DATASOURCE_PASSWORD.

no Java runtime found / Java 17 or newer is required

The host has no suitable Java runtime, or the wrapper cannot find it. Install a Java 17+ runtime, or point JAVA_HOME (or JRE_HOME) at one, and check with java -version.

The application exits during startup

Read the console output — it names the cause. The most common ones are an unreachable database (verify the host and port in DATABASE_URL, and any firewall in between), wrong credentials in SPRING_DATASOURCE_USERNAME / SPRING_DATASOURCE_PASSWORD, or PORT already in use. After an upgrade, a failing migration V26 means the import log check was skipped: run it as described in Stop 1.0 and back it up, then start the application again.

The application starts but the browser cannot reach it

Confirm you are using the port set in PORT (default 8080) and that the host firewall allows it. If the pages load but actions fail behind a reverse proxy, check that the proxy forwards X-Forwarded-Proto and the original host. If users do not see each other’s changes in real time, check that it forwards WebSocket connections on /ws. See TLS hardening.

Something fails once the application is running

Raise the log level with LOG_LEVEL=DEBUG in config.env, restart, and reproduce the problem. See Logs and log levels, and Get support for what to send to Support.