Standalone installation

Install Bonita Process Designer from the self-contained standalone archive, without Docker, 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;

  • docs/ — an offline copy of this documentation;

  • tools/ — 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.

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 for AI features (a corporate proxy is supported — see Configuration reference).

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

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>

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

A single process serves the editor UI and the REST API on PORT. There is no separate back-end port to configure here: BACKEND_PORT applies to the Docker distribution only.

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.

For the full list of configurable variables — ports, TLS, proxy, CORS, AI configuration — see Configuration reference.

3. Start

./start.sh        # Linux / macOS
start.bat         # Windows

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 kbd:[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
ExecStart=/opt/process-designer/start.sh
Restart=on-failure

[Install]
WantedBy=multi-user.target

Under systemd the console output goes to the journal. Read it with journalctl -u process-designer, and see Logs and log levels for retention.

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.

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. For access from another machine, set APP_FRONTEND_URL — and CORS_ORIGIN if you front the application with a reverse proxy on a different origin. See Configuration reference.

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.