This content is dedicated to our next version. It is work in progress: its content will evolve until the new version is released.

Before that time, it cannot be considered as official.

Bonita UI Builder docker configuration guide

This guide provides instructions on how to configure the bonita-ui-builder and bonita-ui-proxy Docker images.

Docker container Environment variables

Configure the bonita-ui-builder image

The following environment variable is mandatory:

  • BONITA_API_URL: The URL for the Bonita API. This should point to the bonita-ui-proxy service (e.g., http://bonita-ui-proxy/bonita/API) to ensure proper request routing.

  • APPSMITH_ENCRYPTION_PASSWORD: The encryption password is critical for safeguarding your datasource credentials through encryption. Set a strong password of your choice that exhibits a good level of entropy to prevent easy decryption.

  • APPSMITH_ENCRYPTION_SALT: The encryption salt contributes to the security strategy by adding a layer of complexity during the encryption process. Set a strong salt of your choice in order to make it more resistant to attacks such as brute-force attempts.

The following environment variables are optional:

  • BONITA_HEALTHCHECK_USER: Defines the username to request the Bonita healthcheck API (default: monitoring).

  • BONITA_HEALTHCHECK_PASSWORD: Defines the password to request the Bonita healthcheck API (default: mon1tor1ng_adm1n).

  • BONITA_DEV_MODE: Enables user to development mode when set to true (default: true).

  • LOGGING_LEVEL_ROOT: Sets the logging level for the root logger (default: debug).

  • LOGGING_LEVEL_COM_APPSMITH: Sets the logging level for Appsmith components (default: debug).

  • LOGGING_LEVEL_COM_BONITASOFT: Sets the logging level for BonitaSoft components (default: debug).

  • LOGGING_LEVEL_COM_EXTERNAL_PLUGINS: Sets the logging level for external plugins (default: debug).

  • BONITA_APPLICATION_EXPORT_PATH: Internal Path to export Bonita UIB Application from Bonita Runtime (default: /opt/appsmith/workspace/app/exports/).

  • BONITA_ENABLE_ZOOM: Enables zoom in deployed applications when set to true (default: false).

Beta Feature: Zoom Controls for Deployed Applications

Zoom controls can be enabled. When enabled, end users can zoom in and out when viewing the deployed application for better accessibility.

This feature is disabled by default and must be explicitly enabled for each instance.

However, this feature may cause display issues in certain scenarios, such as:

  • Widget alignment may appear offset at certain zoom levels

  • Some UI elements may not scale correctly

  • Drag and drop behavior may be affected when zoomed

Use this feature with caution. If you experience display issues, disable the feature in the application’s Zoom settings.

If you want to see the applications export in your file system, you need to mount a volume on the path defined in the BONITA_APPLICATION_EXPORT_PATH variable.

Configure the bonita-ui-proxy image

The bonita-ui-proxy image is based on the official Nginx Docker image. It includes a custom nginx.conf file built to establish communications between Bonita UI Builder and a Bonita Runtime.

The following environment variables are available to customize the configuration:

  • NGINX_ACCESS_LOG_ALL: By default, 2xx and 3xx requests are not logged. Set to 1 to log all requests (default: 0).

  • NGINX_LISTEN_ADDRESS: The address host:[port] on which Nginx is listen on for incoming requests (default: 80). More information on the Nginx documentation.

  • NGINX_EXTERNAL_PORT: The external port used to access Nginx from outside the container. Set this to match the host port mapping in your docker-compose.yml when using a non-standard port (default: 80). For example, if you map port 8888 on the host to port 80 in the container (8888:80), set this variable to 8888.

  • BONITA_HOST: Host of the Bonita runtime to which UI Builder will request (default: host.docker.internal).

  • BONITA_PORT: Port of the Bonita runtime to which UI Builder will request (default: 8080).

  • UIB_HOST: Host of the UI Builder instance. Use the Docker service name when services are on the same network (e.g., bonita-ui-builder).

  • UIB_PORT: Internal port of the UI Builder instance (default: 80).

To use the provided bonita-ui-proxy Docker image without modification, ensure the Bonita runtime is accessible at http://localhost:8080.

If you want to see our custom Nginx configuration used in this image, run this command:

docker run --rm bonitasoft.jfrog.io/docker/bonita-ui-proxy \
    cat /etc/nginx/templates/nginx.conf.template

Troubleshooting

I cannot access to the Bonita UI Builder.

Cause The Bonita UI Builder is not correctly configured.

Solution Check the environment variables and make sure they are correctly set. The BONITA_API_URL should target the bonita-ui-proxy service, and the proxy’s BONITA_HOST and BONITA_PORT should point to a valid Bonita Runtime.