Deploy Bonita Runtime with Docker

How to install and use the Bonita Runtime Docker distribution.

Prerequisites

A working Docker environment.
Access to Bonita Artifact Repository (for Subscription editions only).

Versioning

Multiple tags exist:

latest: Points to the latest version of the platform
2023.2: Points to the latest maintenance version of the 2023.2 version
2023.2-uX: Tag of a maintenance version of 2023.2 (e.g. 2023.2-u0, 2023.2-u1…)

latest and 2023.2 are tags that change each time a new version of the platform is released. It is safer to use the more complete version tag 2023.2-uX when scripting deployments to ensure the binaries do not change.

Installation procedure

Retrieve a license (Subscription editions only)

Subscription editions require a valid license to start the Bonita Runtime.

First generate a request key into a container with a specific hostname (-h):

docker run --rm -h <hostname> -it bonitasoft.jfrog.io/docker/bonita-subscription:2023.2 /bin/bash ./generateRequestKey.sh

Answer the questions related to the license you want. This will print out the request key and exit automatically from the running container.

Then complete the form on the Customer Service Center to request a license (use the request key previously generated). Follow the requested steps to download the license file (.lic extension).

Copy the license file into a folder that will be mounted as a volume of the docker container. In this example, we will use ~/bonita-lic/.

Alternatively, you can create a named persistent volume in docker to keep license files. See docker documentation on volumes.

Start the container

Community edition
Subscription editions

docker run --name bonita -d -p 8080:8080 bonita:2023.2

docker run --name bonita -h <hostname> -v ~/bonita-lic/:/opt/bonita_lic/ -d -p 8080:8080 bonitasoft.jfrog.io/docker/bonita-subscription:2023.2

Creates a Docker container with the hostname -h defined previously and the volume -v containing your license file.

This fresh start only adds the initial license to the Bonita Runtime. To renew a license on an existing installation, see Update configuration and license section

This command starts a container running the Tomcat Bundle with Bonita Runtime. As the command does not specify any environment variables, this is likely a launch of a Bundle on your host using startup.{sh|bat} (with security hardening on REST and HTTP APIs, cf. Security concerns). It means that Bonita uses an H2 database here.

When the container is up and ready, you can access Bonita at the address http://localhost:8080/bonita and log in using the technical user.

Start the container interactively

You may also run the Bonita container with an interactive shell session in order to control start and stop of the Tomcat bundle. Although the main usage of the Docker image is to automatically start the Bonita runtime, manually start and stop Tomcat may be useful for development or troubleshooting purposes.

Run the container as follows in order to get an interactive bash shell session:

Community edition
Subscription editions

docker run --name bonita -it -p 8080:8080 bonita:2023.2 bash

docker run --name bonita -h <hostname> -v ~/bonita-lic/:/opt/bonita_lic/ -it -p 8080:8080 bonitasoft.jfrog.io/docker/bonita-subscription:2023.2 bash

Then run /opt/files/startup.sh inside the container to start Tomcat. In order to stop Tomcat inside the container, press Ctrl-C.
Repeat this sequence to manually start and stop Tomcat in the container.

Custom Permissions

If your project contains REST API Extensions with custom permissions, you can create a volume and map this volume to a local folder with the custom-permissions-mapping.properties file to use in Bonita Docker image:

docker run --name bonita [...] -v ~/local-folder-path/:/opt/bonita/setup/platform_conf/initial/tenant_template_portal/ [...]

Connect Bonita to a database

By default, the Bonita container works out of the box with an H2 database, but it is not recommended outside a development environment.

Your database can be either a Docker container or an installed service.

Database as a Docker container

We provide preconfigured database images to work with Bonita which are available on Bonita DockerHub, such as:

Those images are built from the GitHub repository bonita-database-docker, and can be further adapted or customized to suit your needs.

The configuration of a database to work with Bonita is detailed in the Database configuration page.

Quick start

Preconfigured database images can be run as followed:

Postgres
MySQL
SQL Server

docker run -d --name bonita-postgres -p 5432:5432 bonitasoft/bonita-postgres:15.4

docker run -d --name bonita-mysql -p 3306:3306 bonitasoft/bonita-mysql:8.0.33

docker run -d --name bonita-sqlserver -p 1433:1433 bonitasoft/bonita-sqlserver:2022-CU4

Using Docker Compose

Below are more complete examples on how to run Bonita with a preconfigured database image using Docker Compose.

Community edition
Subscription editions

Postgres
MySQL
SQL Server

# Example on how to use Postgres (latest available version) with a Community edition of Bonita
services:
  bonita-db:
    image: bonitasoft/bonita-postgres:latest
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: my-secret-pw
    restart: always
    # Uncomment those lines to mount a volume with your dumps
    #volumes:
    #  - ~/my/test/dumps:/opt/bonita/dump

  # In case you have built an Application, use instead as example:
  # my-application:
  #  image: my-application-[my built environment]:[my aplication's semantic version]
  bonita:
    image: bonita:2023.2
    ports:
      - "8080:8080"
    environment:
      - DB_VENDOR=postgres
      - DB_HOST=bonita-db
      - DB_PORT=5432
      - DB_NAME=bonita
      - DB_USER=bonita
      - DB_PASS=bpm
      - BIZ_DB_NAME=business_data
      - BIZ_DB_USER=business_data
      - BIZ_DB_PASS=bpm
    restart: on-failure:2
    depends_on:
      bonita-db:
        # It uses the HEALTHCHECK of the database Docker image
        condition: service_healthy

# Example on how to use MySQL (latest available version) with a Community edition of Bonita
services:
  bonita-db:
    image: bonitasoft/bonita-mysql:latest
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: my-secret-pw
    restart: always

  # In case you have built an Application, use instead as example:
  # my-application:
  #  image: my-application-[my built environment]:[my aplication's semantic version]
  bonita:
    image: bonita:2023.2
    ports:
      - "8080:8080"
    environment:
      - DB_VENDOR=mysql
      - DB_HOST=bonita-db
      - DB_PORT=3306
      - DB_NAME=bonita
      - DB_USER=bonita
      - DB_PASS=bpm
      - BIZ_DB_NAME=business_data
      - BIZ_DB_USER=business_data
      - BIZ_DB_PASS=bpm
    restart: on-failure:2
    depends_on:
      bonita-db:
        # It uses the HEALTHCHECK of the database Docker image
        condition: service_healthy

# Example on how to use SQL Server (latest available version) with a Community edition of Bonita
services:
  bonita-db:
    image: bonitasoft/bonita-sqlserver:latest
    ports:
      - "1433:1433"
    environment:
      MSSQL_SA_PASSWORD: Change-Me-123
    restart: always

  # In case you have built an Application, use instead as example:
  # my-application:
  #  image: my-application-[my built environment]:[my aplication's semantic version]
  bonita:
    image: bonita:2023.2
    ports:
      - "8080:8080"
    environment:
      - DB_VENDOR=sqlserver
      - DB_HOST=bonita-db
      - DB_PORT=1433
      - DB_NAME=bonita
      - DB_USER=bonita
      - DB_PASS=bpm
      - BIZ_DB_NAME=business_data
      - BIZ_DB_USER=business_data
      - BIZ_DB_PASS=bpm
    restart: on-failure:2
    depends_on:
      bonita-db:
        # It uses the HEALTHCHECK of the database Docker image
        condition: service_healthy

Postgres
MySQL
SQL Server

# Example on how to use Postgres (latest available version) with a Subscription edition of Bonita
services:
  bonita-db:
    image: bonitasoft/bonita-postgres:latest
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: my-secret-pw
    restart: always
    # Uncomment those lines to mount a volume with your dumps
    #volumes:
    #  - ~/my/test/dumps:/opt/bonita/dump

  # In case you have built an Application, use instead as example:
  # my-application:
  #  image: my-application-[my built environment]:[my aplication's semantic version]
  bonita:
    # this uses the latest maintenance version, but you can also pin a specific maintenance version such as 2023.2-u0
    image: bonitasoft.jfrog.io/docker/bonita-subscription:2023.2
    # Update the hostname with the one used when generating the license
    hostname: localhost
    volumes:
      # Replace ~/bonita-lic with the folder containing the license
      - ~/bonita-lic:/opt/bonita_lic/
    ports:
      - "8080:8080"
    environment:
      - DB_VENDOR=postgres
      - DB_HOST=bonita-db
      - DB_PORT=5432
      - DB_NAME=bonita
      - DB_USER=bonita
      - DB_PASS=bpm
      - BIZ_DB_NAME=business_data
      - BIZ_DB_USER=business_data
      - BIZ_DB_PASS=bpm
    restart: on-failure:2
    depends_on:
      bonita-db:
        # It uses the HEALTHCHECK of the database Docker image
        condition: service_healthy

# Example on how to use MySQL (latest available version) with a Subscription edition of Bonita
services:
  bonita-db:
    image: bonitasoft/bonita-mysql:latest
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: my-secret-pw
    restart: always

  # In case you have built an Application, use instead as example:
  # my-application:
  #  image: my-application-[my built environment]:[my aplication's semantic version]
  bonita:
    # this uses the latest maintenance version, but you can also pin a specific maintenance version such as 2023.2-u0
    image: bonitasoft.jfrog.io/docker/bonita-subscription:2023.2
    # Update the hostname with the one used when generating the license
    hostname: localhost
    volumes:
      # Replace ~/bonita-lic with the folder containing the license
      - ~/bonita-lic:/opt/bonita_lic/
    ports:
      - "8080:8080"
    environment:
      - DB_VENDOR=mysql
      - DB_HOST=bonita-db
      - DB_PORT=3306
      - DB_NAME=bonita
      - DB_USER=bonita
      - DB_PASS=bpm
      - BIZ_DB_NAME=business_data
      - BIZ_DB_USER=business_data
      - BIZ_DB_PASS=bpm
    restart: on-failure:2
    depends_on:
      bonita-db:
        # It uses the HEALTHCHECK of the database Docker image
        condition: service_healthy

# Example on how to use SQL Server (latest available version) with a Subscription edition of Bonita
services:
  bonita-db:
    image: bonitasoft/bonita-sqlserver:latest
    ports:
      - "1433:1433"
    environment:
      MSSQL_SA_PASSWORD: Change-Me-123
    restart: always

  # In case you have built an Application, use instead as example:
  # my-application:
  #  image: my-application-[my built environment]:[my aplication's semantic version]
  bonita:
    # this uses the latest maintenance version, but you can also pin a specific maintenance version such as 2023.2-u0
    image: bonitasoft.jfrog.io/docker/bonita-subscription:2023.2
    # Update the hostname with the one used when generating the license
    hostname: localhost
    volumes:
      # Replace ~/bonita-lic with the folder containing the license
      - ~/bonita-lic:/opt/bonita_lic/
    ports:
      - "8080:8080"
    environment:
      - DB_VENDOR=sqlserver
      - DB_HOST=bonita-db
      - DB_PORT=1433
      - DB_NAME=bonita
      - DB_USER=bonita
      - DB_PASS=bpm
      - BIZ_DB_NAME=business_data
      - BIZ_DB_USER=business_data
      - BIZ_DB_PASS=bpm
    restart: on-failure:2
    depends_on:
      bonita-db:
        # It uses the HEALTHCHECK of the database Docker image
        condition: service_healthy

To execute it, first create a file docker-compose.yml with a content above, then run the command:

docker compose up -d

Run the command below to view and follow log output from containers:

docker compose logs -f

To shut it down and clear your environment:

docker compose down -v --remove-orphans

Cluster mode

Below is an example on how to simulate the run of Bonita in a cluster mode.

We use Postgres as database and Traefik as an HTTP reverse proxy and load balancer.

After execution, Bonita is available at http://bonita.localhost (the address can be changed with the label traefik.http.routers.bonita.rule).

# Example on how to use Postgres (latest available version) with Bonita in a cluster mode
services:
  bonita-db:
    image: bonitasoft/bonita-postgres:latest
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: my-secret-pw
    restart: always
    # Uncomment those lines to mount a volume with your dumps
    #volumes:
    #  - ~/my/test/dumps:/opt/bonita/dump

  # In case you have built an Application, use instead as example:
  # my-application:
  #  image: my-application-[my built environment]:[my aplication's semantic version]
  bonita:
    # this uses the latest maintenance version, but you can also pin a specific maintenance version such as 2023.2-u0
    image: bonitasoft.jfrog.io/docker/bonita-subscription:2023.2
    # Update the hostname with the one used when generating the license
    hostname: localhost
    volumes:
      # Replace ~/bonita-lic with the folder containing the license
      - ~/bonita-lic:/opt/bonita_lic/
    environment:
      - DB_VENDOR=postgres
      - DB_HOST=bonita-db
      - DB_PORT=5432
      - DB_NAME=bonita
      - DB_USER=bonita
      - DB_PASS=bpm
      - BIZ_DB_NAME=business_data
      - BIZ_DB_USER=business_data
      - BIZ_DB_PASS=bpm
      - CLUSTER_MODE=true
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.bonita.entrypoints=web"
      - "traefik.http.routers.bonita.rule=Host(`bonita.localhost`)"
      - "traefik.http.services.bonita.loadbalancer.server.port=8080"
    restart: on-failure:2
    depends_on:
      bonita-db:
        # It uses the HEALTHCHECK of the database Docker image
        condition: service_healthy

  traefik:
    image: traefik:v2.10.5
    container_name: traefik
    command:
      #- "--log.level=DEBUG"
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
    ports:
      - "80:80"
      - "8080:8080"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"

When starting a cluster from scratch, you need first to start only one instance of the bonita service, because the first node initializes the database schema and populates it.

When the first instance has done starting, you can then run the command below to scale up the service.

docker compose up -d --scale bonita=<num> --no-recreate

Where <num> is the number of bonita instances wanted (e.g. --scale bonita=2).

Database as an installed service

If the database is not a Docker container but an installed service, you can load the configuration with environment variables, for instance:

Community edition
Subscription editions

docker run --name bonita \
    -e DB_VENDOR=postgres \
    -e DB_HOST=172.17.0.2 \
    -e DB_PORT=5432 \
    -e DB_NAME=custombonitadb \
    -e DB_USER=custombonitauser \
    -e DB_PASS=custombonitapass \
    -e BIZ_DB_NAME=custombusinessdb \
    -e BIZ_DB_USER=custombusinessuser \
    -e BIZ_DB_PASS=custombusinesspass \
    -d -p 8080:8080 bonita:2023.2

docker run --name bonita -h <hostname> -v ~/bonita-lic/:/opt/bonita_lic/ \
    -e DB_VENDOR=postgres \
    -e DB_HOST=172.17.0.2 \
    -e DB_PORT=5432 \
    -e DB_NAME=custombonitadb \
    -e DB_USER=custombonitauser \
    -e DB_PASS=custombonitapass \
    -e BIZ_DB_NAME=custombusinessdb \
    -e BIZ_DB_USER=custombusinessuser \
    -e BIZ_DB_PASS=custombusinesspass \
    -d -p 8080:8080 bonitasoft.jfrog.io/docker/bonita-subscription:2023.2

Start Bonita with custom security credentials

Security credentials can be customized using environment variables:

Community edition
Subscription editions

docker run --name bonita \
    -e BONITA_RUNTIME_ADMIN_USERNAME=tech_user \
    -e BONITA_RUNTIME_ADMIN_PASSWORD=secret \
    -e PLATFORM_LOGIN=pfadmin \
    -e PLATFORM_PASSWORD=pfsecret \
    -e MONITORING_USERNAME=monitorAdmin \
    -e MONITORING_PASSWORD=monitor_Secr3t-P455w0rD \
    -d -p 8080:8080 bonita:2023.2

docker run --name bonita -h <hostname> -v ~/bonita-lic/:/opt/bonita_lic/ \
    -e BONITA_RUNTIME_ADMIN_USERNAME=tech_user \
    -e BONITA_RUNTIME_ADMIN_PASSWORD=secret \
    -e PLATFORM_LOGIN=pfadmin \
    -e PLATFORM_PASSWORD=pfsecret \
    -e MONITORING_USERNAME=monitorAdmin \
    -e MONITORING_PASSWORD=monitor_Secr3t-P455w0rD \
    -d -p 8080:8080 bonitasoft.jfrog.io/docker/bonita-subscription:2023.2

The Bonita Runtime is now available using technical login tech_user / secret.

Secure your remote access

Community edition
Subscription editions

This docker image ensures to activate by default static authorization checks (Subscription editions only) on REST API. To be coherent it also deactivates the HTTP API. But for specific needs, like exposing directly the Runtime APIs through HTTP (not to be mixed up with the REST API), you can override this behavior by setting HTTP_API to true:

docker run --name bonita \
    -e HTTP_API=true \
    -e HTTP_API_PASSWORD=S0me-h11p-s3cr3t \
    -d -p 8080:8080 bonita:2023.2

This docker image ensures to activate by both static and dynamic authorization checks on REST API. To be coherent it also deactivates the HTTP API. But for specific needs, like exposing directly the Runtime APIs through HTTP (not to be mixed up with the REST API), you can override this behavior by setting HTTP_API to true:

docker run --name bonita -h <hostname> -v ~/bonita-lic/:/opt/bonita_lic/ \
    -e HTTP_API=true \
    -e HTTP_API_PASSWORD=S0me-h11p-s3cr3t \
    -d -p 8080:8080 bonitasoft.jfrog.io/docker/bonita-subscription:2023.2

Environment variables

When starting the Bonita container, you can adjust the configuration of the Bonita instance by passing one or more environment variables on the Docker run command line or the Docker Compose.

PLATFORM_PASSWORD

This environment variable is recommended for you to use the Bonita image. It sets the platform administrator password for Bonita. If it is not specified, the default password platform will be used.

PLATFORM_LOGIN

This optional environment variable is used in conjunction with PLATFORM_PASSWORD to define the username for the platform administrator. If it is not specified, the default username platformAdmin will be used.

BONITA_RUNTIME_ADMIN_USERNAME

This optional environment variable is used in conjunction with BONITA_RUNTIME_ADMIN_USERNAME to define the username for the technical user. If it is not specified, the default username install will be used.

BONITA_RUNTIME_ADMIN_PASSWORD

This environment variable is recommended for you to use the Bonita image. It sets the technical user password for Bonita. If it is not specified, the default password install will be used.

MONITORING_USERNAME

This optional environment variable is used in conjunction with MONITORING_PASSWORD to define the access to endpoints protected with BASIC Auth access: the Monitoring endpoint, the JMX publisher, and the API health endpoints. If it is not specified, the default monitoring username monitoring will be used.

MONITORING_PASSWORD

This optional environment variable is used in conjunction with MONITORING_USERNAME to define the access to endpoints protected with BASIC Auth access: the Monitoring endpoint, the JMX publisher, and the API health endpoints., the default monitoring password mon1tor1ng_adm1n will be used.

REST_API_DYN_AUTH_CHECKS

Removed & does not work anymore, now you can use BONITA_RUNTIME_AUTHORIZATION_DYNAMICCHECK_ENABLED instead.

BONITA_RUNTIME_AUTHORIZATION_DYNAMICCHECK_ENABLED (Subscription editions only)

This optional environment variable is used to enable/disable dynamic authorization checking on Bonita REST API. The default value is true, which will activate dynamic authorization checking.

HTTP_API

This optional environment variable is used to enable/disable the Bonita HTTP API. The default value is false, which will deactivate the HTTP API. From Bonita 2022.1, HTTP API is protected with Basic access authentication. See the following 2 parameters to configure Basic access authentication.

HTTP_API_USERNAME

This optional environment variable is used to configure the HTTP API Basic access authentication username. The default value is http-api.

HTTP_API_PASSWORD

This optional environment variable is used to configure the HTTP API Basic access authentication password. There is no default value, and providing a value is mandatory if HTTP_API=true.

JMX_REMOTE_ACCESS

This optional environment variable is used to enable/disable the access to the JMX console from a remote machine.
Default value is false.
The host to connect to is the name / IP address of the bonita server, the port to connect to is 9000.
The credentials to connect are the environment variables MONITORING_USERNAME, MONITORING_PASSWORD.

REMOTE_IP_VALVE_ENABLED

This optional environment variable allows to activate/deactivate reverse proxy redirection. Default value is false.

ACCESSLOGS_STDOUT_ENABLED

This optional environment variable allows to activate/deactivate writing Tomcat access logs to standard output. Default value is false.

ACCESSLOGS_FILES_ENABLED

This optional environment variable allows to activate/deactivate writing Tomcat access logs to a specific file. When activated, will write those logs to /opt/bonita/logs/ inside the docker container. In practice, it is only useful when mounting a volume to the aforementioned directory. Default value is false.

ACCESSLOGS_PATH

If ACCESSLOGS_FILES_ENABLED=true, this optional environment variable overrides the default path to of the access log file. Default value is /opt/bonita/logs.

ACCESSLOGS_PATH_APPEND_HOSTNAME

If ACCESSLOGS_FILES_ENABLED=true, this optional environment variable allows to append a subdirectory with the hostname to the full path of the directory to put access log files into. Default value is false.

ACCESSLOGS_MAX_DAYS

If ACCESSLOGS_FILES_ENABLED=true, this optional environment variable allows to automatically delete access log files after a certain number of days. Default value is 30.

HEAPDUMP_PATH

This optional environment variable overrides the default path of the heap dump file. Default value is /opt/bonita/logs.

HTTP_MAX_THREADS

This optional environment variable allows to specify the maximum Http thread number Tomcat will use to serve HTTP/1.1 requests. Directly modifies the maxThreads parameter in the server.xml file of the Tomcat inside the docker container. More information on the usefulness of this parameter can be found here. Default value is 20.

JAVA_OPTS

This optional environment variable is used to customize JAVA_OPTS. The default value is -Xms1024m -Xmx1024m. The syntax to use is -e JAVA_OPTS="-Xms2048m -Xmx2048m"

DB_VENDOR

This environment variable is automatically set to postgres or mysql if the Bonita container is linked to a PostgreSQL or MySQL database using --link. The default value is h2. It can be overridden if you don’t use the --link capability.

DB_HOST, DB_PORT

These variables are optional, used in conjunction to configure the bonita image to reach the database instance. There are automatically set if --link is used to run the container.

BONITA_DS_CONNECTION_POOL_INITIAL_SIZE, BDM_DS_CONNECTION_POOL_INITIAL_SIZE

Change the default value for the Bonita and/or the BDM datasource initialSize. This is the initial number of connections when the connection pool starts.

BONITA_DS_CONNECTION_POOL_MAX_TOTAL, BDM_DS_CONNECTION_POOL_MAX_TOTAL

Change the default value for the Bonita and/or the BDM datasource maxTotal. This is the maximum number of active connections that can be allocated from this pool at the same time.

BONITA_DS_CONNECTION_POOL_MIN_IDLE, BDM_DS_CONNECTION_POOL_MIN_IDLE

Change the default value for the Bonita and/or the BDM datasource minIdle. This is the minimum number of active connections that always established after pool created and connection has reached this size.

BONITA_DS_CONNECTION_POOL_MAX_IDLE, BDM_DS_CONNECTION_POOL_MAX_IDLE

Change the default value for the Bonita and/or the BDM datasource maxIdle. This is the maximum number of connections that should be kept in the pool at all times.

DB_NAME, DB_USER, DB_PASS

These variables are used in conjunction to create a new user, set that user’s password, and create the bonita database.

DB_NAME default value is bonitadb.

DB_USER default value is bonitauser.

DB_PASS default value is bonitapass.

BIZ_DB_NAME, BIZ_DB_USER, BIZ_DB_PASS

These variables are used in conjunction to create a new user, set that user’s password and create the bonita business database.

BIZ_DB_NAME default value is businessdb.

BIZ_DB_USER default value is businessuser.

BIZ_DB_PASS default value is businesspass.

BONITA_SERVER_LOGGING_FILE, BONITA_SETUP_LOGGING_FILE

DEPRECATED See how to configure logger

Since Bonita 7.9 BONITA_SERVER_LOGGING_FILE and BONITA_SETUP_LOGGING_FILE can be used to update logging configuration.

BONITA_SERVER_LOGGING_FILE default value is /opt/bonita/conf/logs/log4j2-appenders.xml,/opt/bonita/conf/logs/log4j2-loggers.xml

BONITA_SETUP_LOGGING_FILE default value is /opt/bonita/setup/logback.xml

BONITA_RUNTIME_STARTUP_UPDATE_ONLY

When set to true, the application exit right after the initialization/update phase. Exit with the 0 exit code when no errors occurred during the startup phase, 1 otherwise.

CLUSTER_MODE

This environment variable activates the Cluster mode on Bonita, allowing to start several nodes that will join the cluster.

This will automatically disable Hibernate L2 cache.

Logger configuration

To ease the logger configuration, you can mount a volume on folder /opt/bonita/conf/logs containing the configuration files:

docker run -v ~/my-config/log4j/:/opt/bonita/conf/logs/ ...

The volume must contain the 2 files log4j2-loggers.xml and log4j2-appenders.xml

Log4j2 automatically reloads configuration files when there is a change. However, if the file is invalid, the initial version of that file is used instead, and is not reloaded unless one of the other watched file is changed.

If no user is specified to create the container (--user), the filesystem access rights are downgraded to allow only the bonita user (inside the Docker container), meaning that a standard user cannot access the log4j2 configuration folder on the host machine (~/my-config/log4j/ in this example) anymore. Make sure to access it as a "sudoer" to hot-modify the logger configuration, or specify a dedicated user when creating the container:

docker run --user <my-dedicated-bonita-user> -v ~/my-config/log4j/:/opt/bonita/conf/logs/ ...

Migrating from an earlier version of Bonita

The migration scripts affect only the database, not the Bonita instance. The procedure to migrate a Bonita container is therefore as follows:

Stop and destroy the running Bonita container.
Play the migration script on your Bonita database see migrate the platform from an earlier version of Bonita.
Get the new Bonita docker image, as explained above.
Update the license, see Update configuration and license section
Start a new Bonita container.

Update configuration and license

Once renewed from Bonita Customer Portal, the license file and the configuration files are updated using the Setup Tool.

Setup tool can be used outside the Docker container directly by downloading the Tomcat bundle and running it from there.

The Setup Tool requires access to the database. Because of that, if the database is running inside a Docker container, the dedicated port must be exposed to the host.

See the Setup Tool page for more information.

Troubleshoot and debug problems inside a Docker container

Bonita 2023.2 Docker image comes with a set of tools embedded, jattach, that allows to interact with the Tomcat JVM inside a Bonita container via Dynamic Attach mechanism.

Example of useful commands it supports, that you can run from outside the container, include:

docker exec <CONTAINER_NAME> jattach 1 jcmd VM.flags to see all JVM flags passed to Bonita Tomcat JVM:

Connected to remote JVM
JVM response code = 0
-XX:CICompilerCount=4 -XX:ConcGCThreads=2 -XX:G1ConcRefinementThreads=8 -XX:G1HeapRegionSize=1048576 -XX:GCDrainStackTargetSize=64 -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/opt/bonita/server/logs

docker exec <CONTAINER_NAME> jattach 1 properties to see all System properties that Java will use:

Connected to remote JVM
JVM response code = 0
#Fri Sep 10 14:03:16 GMT 2021
com.arjuna.ats.arjuna.common.propertiesFile=/opt/bonita/server/conf/jbossts-properties.xml
sysprop.bonita.bdm.db.vendor=h2
awt.toolkit=sun.awt.X11.XToolkit
java.specification.version=11
sun.cpu.isalist=
sun.jnu.encoding=ANSI_X3.4-1968
java.class.path=/opt/bonita/server/lib/ext/bonita-tomcat-juli-9.0.0.jar\:/opt/bonita/server/bin/bootstrap.jar\:/opt/bonita/server/bin/tomcat-juli.jar
sysprop.bonita.db.vendor=h2
java.vm.vendor=Ubuntu

Read the official jattach documentation for a complete list of supported commands.