Bonita UI Builder docker configuration guide

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

Upgrade checkpoint for existing installations

If you run a version older than 1.3.12 and have persistent MongoDB data (a mounted volume), you must upgrade to 1.3.12 before upgrading to any later version.

Skipping this version causes MongoDB to fail to start in subsequent releases.

Why?

This release upgrades the bundled MongoDB Feature Compatibility Version (FCV) to 6. Later versions require MongoDB 7, which refuses to open a database still at FCV 5. Upgrading through 1.3.12 performs this FCV migration automatically.

Fresh installations (no existing volume) are not affected and can install any version directly.

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_API_AUTOCOMPLETE Since 1.3.15 (for development mode only): Enable the Bonita API autocompletion to help you to fill the Bonita request query (default: false prior 1.3.17, true since 1.3.17).

  • 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 UIB components (default: debug).

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

  • LOGGING_PATTERN_CONSOLE: Logback pattern used for the backend log lines (default: [%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX}] [%thread] [%5p] %logger{36} - %msg%n). Since 1.3.18 the default carries milliseconds and the zone offset, so that two events of the same second can be ordered and the timestamps can be compared with anything collected elsewhere.

  • LOGGING_STRUCTURED_FORMAT_CONSOLE: Logs the backend as JSON instead of plain text, one object per event (logstash, ecs or gelf; unset by default). Recommended when a log collection system ingests the logs, so that every field is queryable and a stack trace stays inside the event that produced it instead of being split into one entry per stack-trace line. See Structured JSON logs for details.

  • LOGGING_STRUCTURED_JSON_STACKTRACE_ROOT: Prints the root cause first or last in a stack trace (default: last). Applies only when LOGGING_STRUCTURED_FORMAT_CONSOLE is set, as do the four variables below.

  • LOGGING_STRUCTURED_JSON_STACKTRACE_INCLUDEHASHES: Adds a fingerprint of each stack trace, so that a collector can group repeated occurrences of the same exception (default: false).

  • LOGGING_STRUCTURED_JSON_STACKTRACE_MAXTHROWABLEDEPTH: Caps the number of frames printed for each throwable of the chain (default: unlimited).

  • LOGGING_STRUCTURED_JSON_STACKTRACE_MAXLENGTH: Caps the number of characters of a stack trace (default: unlimited).

  • LOGGING_STRUCTURED_JSON_STACKTRACE_INCLUDECOMMONFRAMES: Keeps the frames a throwable shares with the one wrapping it (default: false).

  • 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.

  • BONITA_MAX_DECOMPRESSED_ENTRY_SIZE_BYTES: Since 1.3.13 Per-entry cap (in bytes) on the decompressed size of a single file when importing a bundle, to guard against ZIP bombs (default: 52428800, i.e. 50 MB).

  • BONITA_MAX_DECOMPRESSED_TOTAL_SIZE_BYTES: Since 1.3.13 Cumulative cap (in bytes) on the total decompressed size of an imported bundle, to guard against ZIP bombs (default: 524288000, i.e. 500 MB).

  • BONITA_FORCE_DESKTOP_VIEWPORT: Since 1.3.15 Forces a desktop viewport on deployed applications, preventing mobile browsers from applying their default scaling behavior (default: false).

Reserved ports (do NOT use for UIB_INTERNAL_PORT):

Reserved Port

Services

2019

Caddy admin API

6379

Redis

8080

Backend (Spring Boot)

8091

RTS (WebSocket)

9001

Supervisor

27017

MongoDB

Safe choices: 8090, 8082, 3000, or any other unused port.

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.

  • UIB_NPM_REDIRECT Since 1.3.17: Controls how requests to /npm/…​ are answered (default: off). Safari resolves the module preloads advertised by public content delivery networks such as jsDelivr against the application domain instead of the delivery network (WebKit bug 269635, Safari 17 to 26.6), which sends hundreds of unwanted requests per widget load to UI Builder. These requests are always answered by the proxy itself, before authentication, so they never reach the Bonita runtime. With off they are answered with a 404 and logged; set it to on to redirect them to the content delivery network instead, so that the preloads are used rather than wasted.

  • UIB_NPM_CDN Since 1.3.17: Origin the redirection points at, which can be a private mirror (default: https://cdn.jsdelivr.net). A trailing slash is ignored. Ignored when UIB_NPM_REDIRECT is off.

  • UIB_NPM_CACHE_CONTROL Since 1.3.17: Value of the Cache-Control header set on the redirect response, so that browsers can reuse it instead of asking again on every load (default: empty, no header is sent). Ignored when UIB_NPM_REDIRECT is off.

  • BONITA_OPENAPI_URL: Since 1.3.15, in Development only. URL of the Bonita OpenAPI contract used to power API endpoint autocompletion in the query editor (see Common APIs to use).

UI Builder fetches the OpenAPI contract from BONITA_OPENAPI_URL at runtime and caches it to provide API endpoint autocompletion. If the contract cannot be retrieved (for example in an air-gapped environment), UI Builder runs in degraded mode and falls back to a frozen version of the contract bundled in UI Builder.

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

Structured JSON logs

The container writes one JSON object per line on its standard output, whatever the format of the backend log lines is. Each line carries the time of the event (@timestamp), its message and level, the service and the stream it came from (process and channel), and a seq number ordering the lines that share the same millisecond. Stack traces are attached to the event that produced them, in a stack_trace field, instead of becoming one entry per stack-trace line.

The backend itself logs plain text lines, formatted by LOGGING_PATTERN_CONSOLE, which is the easiest format to read yourself. When a log collection system ingests the logs, log the backend as JSON instead:

bonita-ui-builder:
  environment:
    LOGGING_STRUCTURED_FORMAT_CONSOLE: logstash
    LOGGING_STRUCTURED_JSON_STACKTRACE_ROOT: first
    LOGGING_STRUCTURED_JSON_STACKTRACE_INCLUDEHASHES: "true"
    LOGGING_STRUCTURED_JSON_STACKTRACE_MAXTHROWABLEDEPTH: "30"

Every field of an event then becomes a queryable attribute, and @timestamp, message and level are the names most collectors map on their own.

Structured logging requires UI Builder 1.3.15 or later. On earlier versions these variables are ignored without any error.

The variable names drop the hyphens of the underlying property name rather than turning them into underscores: logging.structured.json.stacktrace.max-throwable-depth becomes LOGGING_STRUCTURED_JSON_STACKTRACE_MAXTHROWABLEDEPTH. A name written with an extra underscore binds to nothing and is silently ignored.

The log files under /appsmith-stacks/logs/ are not in that shape: they hold the raw output of each process, as the process wrote it.

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.