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: Since 1.3.6 Enables zoom in deployed applications when set to true (default: false).

  • UIB_INTERNAL_PORT: Since 1.3.9 The internal HTTP port the UI Builder listens on (default: 80). Set to a non-80 value when port 80 is already occupied inside the container, for example on Kubernetes platforms where a sidecar proxy binds to port 80. See Custom internal port (Kubernetes / sidecar proxy) for details.

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). Must match the UIB_INTERNAL_PORT value set on the bonita-ui-builder container.

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

Custom internal port (Kubernetes / sidecar proxy)

By default, the bonita-ui-builder container listens on port 80. On some Kubernetes platforms (e.g., Null Platform, Istio, Linkerd), a sidecar proxy is automatically injected into every Pod and also binds to port 80. Since all containers in a Pod share the same network namespace, the UI Builder fails to start with a port conflict.

To solve this, set UIB_INTERNAL_PORT to a different port on the bonita-ui-builder container, and update UIB_PORT on the bonita-ui-proxy container to match.

Configuration

Set the following environment variables:

Variable Container Description Default

UIB_INTERNAL_PORT

bonita-ui-builder

Internal port the UI Builder listens on

80

UIB_PORT

bonita-ui-proxy

Port the proxy uses to reach UI Builder (must match UIB_INTERNAL_PORT)

80

NGINX_LISTEN_ADDRESS

bonita-ui-proxy

Internal port NGINX listens on (change if port 80 is also occupied on the proxy container)

80

Docker Compose example

services:
  bonita-ui-builder:
    image: {bonita-ui-builder-image}:${UIB_VERSION}
    environment:
      BONITA_API_URL: http://bonita-ui-proxy:${NGINX_LISTEN_ADDRESS:-80}/bonita/API
      UIB_INTERNAL_PORT: 8090  (1)

  bonita-ui-proxy:
    image: {bonita-ui-proxy}:${UIB_VERSION}
    environment:
      NGINX_LISTEN_ADDRESS: ${NGINX_LISTEN_ADDRESS:-80}
      UIB_HOST: bonita-ui-builder
      UIB_PORT: 8090  (2)
      BONITA_HOST: bonita
      BONITA_PORT: 8080
    ports:
      - "${NGINX_HTTP_PORT:-80}:${NGINX_LISTEN_ADDRESS:-80}"
1 Caddy inside the UI Builder now listens on port 8090 instead of 80.
2 Must match the UIB_INTERNAL_PORT value so the proxy routes traffic to the correct port.

Kubernetes example

In a Kubernetes manifest or Helm values, set the environment variables directly:

# bonita-ui-builder container
env:
  - name: UIB_INTERNAL_PORT
    value: "8090"
ports:
  - containerPort: 8090
livenessProbe:
  httpGet:
    port: 8090
    path: /

# bonita-ui-proxy container
env:
  - name: UIB_PORT
    value: "8090"
  - name: NGINX_LISTEN_ADDRESS
    value: "8082"
ports:
  - containerPort: 8082

Verification

After starting, verify the configuration:

# Port 80 should be free inside the UI Builder container
docker exec bonita-ui-builder curl -s -o /dev/null -w "%{http_code}" --max-time 2 http://localhost:80/
# Expected: 000 (connection refused)

# UI Builder should respond on the custom port
docker exec bonita-ui-builder curl -s -o /dev/null -w "%{http_code}" --max-time 2 http://localhost:8090/
# Expected: 200

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.