Configuration reference

The environment variables an operator sets to configure Bonita Process Designer, with their purpose, defaults, and security notes.

Bonita Process Designer is configured through environment variables, set either in your deployment’s environment, in the Docker Compose .env file, or in the config.env file of the standalone distribution. This page lists the variables you are most likely to set, then explains the CORS and TLS security settings in more detail.

Only DATABASE_URL, SPRING_DATASOURCE_USERNAME, and SPRING_DATASOURCE_PASSWORD are required. Every other variable has a sensible default; set the rest only when your deployment needs them.

Environment variable reference

Variable Purpose Default

Variable	Purpose	Default
`DATABASE_URL`	JDBC URL of the PostgreSQL instance, in the form `jdbc:postgresql://<host>:<port>/<database>`. Required.	(none)
`SPRING_DATASOURCE_USERNAME`	PostgreSQL user. Required.	(none)
`SPRING_DATASOURCE_PASSWORD`	PostgreSQL password. Required.	(none)
`PORT`	HTTP port. In the Docker distribution: the front-end service serving the editor UI. In the standalone distribution: the single process serving both the editor UI and the API. See the note below.	`8080`
`BACKEND_PORT`	Docker distribution only: the back-end API port, which must be visible to both the front-end and back-end services. It has no effect in the standalone distribution. See the note below.	`3000`
`CORS_ORIGIN`	Comma-separated list of exact origins allowed to call the API. Overrides the automatic same-host derivation. Wildcards are not supported. See CORS security.	auto-derived from the request host on port 8080
`USE_HTTPS`	Set to `true` when the application is served over HTTPS (behind a TLS-terminating reverse proxy). Makes the session cookie `Secure` and sets `SameSite=None`, which is required for cross-host HTTPS access. See TLS hardening.	`false`
`HTTP_PROXY`	Proxy URL for outbound HTTP traffic (AI generation) on hosts without direct internet access.	(none)
`HTTPS_PROXY`	Proxy URL for outbound HTTPS traffic.	(none)
`NO_PROXY`	Comma-separated hosts that bypass the proxy (for example `localhost,127.0.0.1,postgres`).	(none)
`AUTH_MODE`	Authentication mode: `standalone` (username/password with a server session) or `bonita` (delegate to a Bonita Runtime). See Run with Bonita Runtime.	`standalone`
`LOG_LEVEL`	Verbosity of the application’s own log. Raise to `DEBUG` when diagnosing a problem. Read at startup — restart to apply. See Logs and log levels.	`INFO`
`LOG_LEVEL_ROOT`	Verbosity of everything else: framework, database driver, and other libraries. Raise only when the problem looks lower-level than the application itself. A few framework loggers are pinned separately and are not affected by it — see `LOG_LEVEL_TOMCAT_HTTP`.	`INFO`
`LOG_LEVEL_TOMCAT_HTTP`	Verbosity of Tomcat’s HTTP protocol logger, pinned independently of `LOG_LEVEL_ROOT` and deliberately quieter than it, because at `INFO` this logger writes request data that is otherwise never recorded. Leave it alone unless you are diagnosing a protocol-level rejection, and read the warning below first.	`WARN`
`LOGGING_FILE_NAME`	Standalone only: where to write the log file. Set it to place the log on a dedicated partition; the directory must exist and be writable. See Writing the file elsewhere.	`logs/process-designer.log`
`LOGGING_LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE`	Standalone only: size at which the log file rolls over.	`10MB`
`LOGGING_LOGBACK_ROLLINGPOLICY_MAX_HISTORY`	Standalone only: days of gzipped archives to keep.	`30`
`LOGGING_LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP`	Standalone only: total size the log file and its archives may occupy. Once reached, the oldest archives are deleted first.	`1GB`

DATABASE_URL

JDBC URL of the PostgreSQL instance, in the form jdbc:postgresql://<host>:<port>/<database>. Required.

(none)

SPRING_DATASOURCE_USERNAME

PostgreSQL user. Required.

(none)

SPRING_DATASOURCE_PASSWORD

PostgreSQL password. Required.

(none)

PORT

HTTP port. In the Docker distribution: the front-end service serving the editor UI. In the standalone distribution: the single process serving both the editor UI and the API. See the note below.

8080

BACKEND_PORT

Docker distribution only: the back-end API port, which must be visible to both the front-end and back-end services. It has no effect in the standalone distribution. See the note below.

3000

CORS_ORIGIN

Comma-separated list of exact origins allowed to call the API. Overrides the automatic same-host derivation. Wildcards are not supported. See CORS security.

auto-derived from the request host on port 8080

USE_HTTPS

Set to true when the application is served over HTTPS (behind a TLS-terminating reverse proxy). Makes the session cookie Secure and sets SameSite=None, which is required for cross-host HTTPS access. See TLS hardening.

false

HTTP_PROXY

Proxy URL for outbound HTTP traffic (AI generation) on hosts without direct internet access.

(none)

HTTPS_PROXY

Proxy URL for outbound HTTPS traffic.

(none)

NO_PROXY

Comma-separated hosts that bypass the proxy (for example localhost,127.0.0.1,postgres).

(none)

AUTH_MODE

Authentication mode: standalone (username/password with a server session) or bonita (delegate to a Bonita Runtime). See Run with Bonita Runtime.

standalone

LOG_LEVEL

Verbosity of the application’s own log. Raise to DEBUG when diagnosing a problem. Read at startup — restart to apply. See Logs and log levels.

INFO

LOG_LEVEL_ROOT

Verbosity of everything else: framework, database driver, and other libraries. Raise only when the problem looks lower-level than the application itself. A few framework loggers are pinned separately and are not affected by it — see LOG_LEVEL_TOMCAT_HTTP.

INFO

LOG_LEVEL_TOMCAT_HTTP

Verbosity of Tomcat’s HTTP protocol logger, pinned independently of LOG_LEVEL_ROOT and deliberately quieter than it, because at INFO this logger writes request data that is otherwise never recorded. Leave it alone unless you are diagnosing a protocol-level rejection, and read the warning below first.

WARN

LOGGING_FILE_NAME

Standalone only: where to write the log file. Set it to place the log on a dedicated partition; the directory must exist and be writable. See Writing the file elsewhere.

logs/process-designer.log

LOGGING_LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE

Standalone only: size at which the log file rolls over.

10MB

LOGGING_LOGBACK_ROLLINGPOLICY_MAX_HISTORY

Standalone only: days of gzipped archives to keep.

30

LOGGING_LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP

Standalone only: total size the log file and its archives may occupy. Once reached, the oldest archives are deleted first.

1GB

Setting LOG_LEVEL_TOMCAT_HTTP=INFO makes Tomcat log the whole rejected request when a malformed request line or a non-conforming header arrives: the request target with its query string, and the offending header line with its value — which can be the Cookie or Authorization header. Session identifiers, credentials and query strings are otherwise never written to the log (see Logs and log levels).

Use it only briefly, and treat the log it produces as sensitive: it is no longer safe to send to Support unreviewed. Raising LOG_LEVEL_ROOT alone does not surface these lines, because this logger is pinned independently — which is the point.

The four LOGGING_* variables apply to the standalone distribution only. The Docker distribution writes no log file inside its containers — its logs are the containers' output, and their retention belongs to the Docker logging driver. See Logs and log levels.

PORT and BACKEND_PORT apply to the Docker distribution, where the editor UI and the API run as two separate services. The standalone distribution is a single process that serves both on PORT alone — BACKEND_PORT has no effect there. See Standalone installation.

The standalone distribution accepts the optional APP_FRONTEND_URL variable to set the public URL used in editor deep links (default http://localhost:8080). See Standalone installation.

AI configuration

AI diagram generation is configured by an administrator in the application, not through environment variables. After registration, an Admin enters one or more LLM provider keys under Admin → Settings. Bonita Process Designer does not store these provider keys in its own database — it persists only a per-provider "configured" flag so the admin UI can show which providers have a key. Use a dedicated, scoped key per provider and rotate keys periodically.

Set spend caps and usage limits in each provider’s own dashboard. The application’s per-group AI quota is a complementary control, not a substitute for a provider-side spend cap.

Secrets and the encryption key

There is no shared session-signing secret to configure on Bonita Process Designer. Session identifiers are random and stored server-side in PostgreSQL, so the security of session data depends on protecting the database and serving over HTTPS — not on a secret you set.

Likewise, LLM provider keys are never persisted locally (see AI configuration), so there is no application-level key-encryption secret to manage. Keep your PostgreSQL credentials strong and unique, and keep the database on a private network segment reachable only by the back-end.

CORS security

By default the back-end derives the allowed origin from the request host on port 8080, so a single-host deployment needs no CORS configuration. For any multi-host, reverse-proxy, or custom-domain deployment, set CORS_ORIGIN to the exact front-end origins:

# Single explicit origin
CORS_ORIGIN=http://custom-domain.com:8080

# Multiple origins (comma-separated)
CORS_ORIGIN=http://192.168.1.100:8080,http://app.example.com:8080

Never use a wildcard origin with credentials. Wildcard CORS is a CSRF vector and is intentionally unsupported. Always list exact origins.

TLS hardening

Bonita Process Designer serves HTTP; terminate TLS in front of it with a reverse proxy (such as nginx, Traefik, or Caddy) or a load balancer rather than exposing the application directly. When served over HTTPS:

Set USE_HTTPS=true so the session cookie is issued with the Secure flag. Enabling HTTPS also sets the cookie attribute SameSite=None (in addition to Secure), which is required for cross-host HTTPS access. Leaving it false behind HTTPS would emit a non-Secure cookie.
Forward X-Forwarded-Proto and X-Forwarded-Host from the proxy so origin derivation and the Secure flag behave correctly.

USE_HTTPS=true

For the full operator hardening checklist — TLS, CORS, account and database hardening, proxy configuration, and Bonita Runtime mode — see First-time setup and review the deployment-mode guidance in Run with Bonita Runtime.