Upgrade Process Designer

Upgrade a Bonita Process Designer 1.0.x installation to 1.1: prepare, back up the database, check it, replace the application, and review what changes for your scripts and your users.

This page describes upgrading to Bonita Process Designer 1.1.

This page covers an upgrade from any 1.0.x version (1.0.0, 1.0.1 or 1.0.2) to 1.1.0, for the Docker and the standalone distributions. For the list of new features and fixes, see Release notes.

Before you start

Read this section before you stop anything.

The upgrade cannot be undone. At its first start, 1.1 runs the database migrations V21 to V28 automatically, with no manual step. A database migrated to 1.1 must not be used by 1.0: 1.0 would start on it without refusing; the only sign is a Flyway warning in its log. To go back to 1.0, you restore the backup taken before the upgrade, and every change made in 1.1 is lost. See Go back to 1.0.
Back up once users have stopped working, after the application is stopped and before 1.0 is removed: changes made after the backup are lost if you go back to 1.0. The procedures below take the backup at that point.
Get 1.1 first. Download the archive of your distribution from the Customer Service Center. For Docker, you can instead download the 1.1 Compose files from the documentation and pull the image from the Bonita Artifact Repository: see Get the application.
Keep the downtime short. The application is unavailable between the moment you stop 1.0 and the moment 1.1 has started, and the first start of 1.1 takes longer than usual, because it runs the migrations. Extract the archive, load the image or install Java while 1.0 is still running, as the procedures below do.
License enforcement cannot be turned off any more. The LICENSE_BYPASS variable is removed. An installation that ran with LICENSE_BYPASS=true refuses every request except sign-in and the license page until a valid .lic file is installed. Make sure you have one before you upgrade. See Manage the license.
Know which 1.0.x version you run. The page footer shows 1.0.0 for every 1.0.x version, so check the installation itself:
- Docker: docker image ls | grep process-designer (findstr instead of grep on Windows) lists process-designer-backend and process-designer-frontend with the tag v1.0.0 for 1.0.0, and process-designer with the tag v1.0.1 or v1.0.2 for the later versions. From the directory of your docker-compose.yml, docker compose ps lists the services backend and frontend in 1.0.0, and a single app service in 1.0.1 and 1.0.2. Its IMAGE column shows the version actually running, for example process-designer:v1.0.2.
- Standalone: the folder extracted from the archive carries the version in its name. The 1.0.0 folder, process-designer-1.0.0-standalone-<platform>, contains jre/, node/, back-end/ and front-end/. The 1.0.1 and 1.0.2 folders, process-designer-1.0.1-standalone and process-designer-1.0.2-standalone, contain app.jar.

If something goes wrong during the upgrade, see the troubleshooting section of Install with Docker or of Standalone installation before you decide to go back to 1.0.

Upgrade the Docker distribution

The 1.1 archive keeps the Compose project name and the volume names of 1.0.x. Your database and the certificate authority that Caddy generated are therefore kept, and so is your license file when you upgrade from 1.0.1 or 1.0.2. The 1.1 stack uses the same postgres:16-alpine and caddy:2-alpine images as 1.0.x, which are already on the host.

The docker compose commands below work in any shell, including Windows PowerShell. If you run 1.0.1 or 1.0.2 with the plaintext HTTP opt-out, add -f docker-compose.http.yml to each docker compose command, in the 1.0 directory as in the new one.

Prepare, while 1.0 still runs

Extract the 1.1 archive for your architecture (process-designer-1.1.0-amd64.zip or process-designer-1.1.0-arm64.zip) into a new directory. The archive has no root folder, so give it one, for example:
```
unzip process-designer-1.1.0-amd64.zip -d /opt/process-designer-1.1
```
To pull the image from the Bonita Artifact Repository instead, create the new directory and download the 1.1 Compose files into it, as described in From the Bonita Artifact Repository.
Carry your settings over to the new directory:
- Copy your .env file, if you have one.
- If you passed TLS_DOMAIN, CORS_ORIGIN, APP_FRONTEND_URL or USE_HTTPS on the command line of docker compose up, nothing carries them over: write them to a .env file in the new directory now. See Access the application from other machines.
- Copy your certs/ folder, if you use your own certificate.
- If you changed the database password in the 1.0 docker-compose.yml and you install the Compose files of the Bonita Artifact Repository, write it to the .env file instead, as POSTGRES_PASSWORD: those files read it there. See Database password.
- If you edited the 1.0 docker-compose.yml or Caddyfile (proxy variables, certificate, database password with the files of the archive, JAVA_OPTS), make the same edits in the 1.1 files. Do not copy the 1.0 files over the 1.1 ones: the 1.0.0 files describe services that no longer exist, and the 1.1 docker-compose.yml adds the log caps and the log level variables. JAVA_OPTS had no effect in 1.0.x and takes effect in 1.1: a value left over from 1.0, such as -Xmx4g, now applies.

From the new directory, load the new image. On Linux and macOS:

chmod +x install.sh && ./install.sh

On Windows, in Windows PowerShell:

.\install.bat

In cmd.exe, type install.bat.

To pull the image from the Bonita Artifact Repository instead, run, from the new directory:

docker login bonitasoft.jfrog.io
docker compose pull app

docker compose pull only downloads the image: it does not touch the running 1.0 containers.

Do not run docker compose up in the new directory yet, even though the script suggests it. Both directories use the same Compose project, so it would replace the running 1.0 containers and migrate the database before you have backed it up.

Stop 1.0 and back it up, once users have stopped working

Run these commands from the directory of the 1.0 docker-compose.yml.

If you upgrade from 1.0.0, copy the license file out of the backend container: 1.0.0 kept it inside the container, which docker compose down deletes.
```
docker compose cp backend:/app/licenses ./licenses-1.0.0
```

Stop the application, and leave the database running:

docker compose stop backend frontend     # 1.0.0
docker compose stop app                  # 1.0.1 and 1.0.2

Back up the database, and copy the backup out of the container:
```
docker compose exec -T postgres pg_dump -U postgres -Fc -f /tmp/backup-1.0.dump bpmnDB
docker compose exec -T postgres pg_restore --list /tmp/backup-1.0.dump
docker compose cp postgres:/tmp/backup-1.0.dump ./backup-1.0.dump
```
The second command reads the backup back: it must list the contents of the dump and end without an error. Keep backup-1.0.dump until you have checked that 1.1 works for your users, and keep a copy of it outside the Docker host.
Check the import logs. Migration V26 adds length limits (255, 255 and 2,000 characters) to the import log table, and PostgreSQL checks them against the existing rows. If a row exceeds a limit, the migration fails and the application does not start. This is not expected with import logs written by the editor, but run this check:
```
docker compose exec -T postgres psql -U postgres -d bpmnDB -c "SELECT count(*) FROM migration_entries WHERE char_length(element_id) > 255 OR char_length(original_type) > 255 OR char_length(reason) > 2000;"
```
If the count is not zero, delete those import log rows. You only lose these lines of import reports:
```
docker compose exec -T postgres psql -U postgres -d bpmnDB -c "DELETE FROM migration_entries WHERE char_length(element_id) > 255 OR char_length(original_type) > 255 OR char_length(reason) > 2000;"
```
Stop 1.0:
```
docker compose down
```
Never add -v. docker compose down -v deletes the volumes: the database, the license file and the certificate authority of Caddy.

Start 1.1

From the new directory, start the stack:
```
docker compose up -d
```
If you used the plaintext HTTP opt-out, start with docker compose -f docker-compose.http.yml up -d instead.
Follow the application log until it shows Started ProcessDesignerApplication:
```
docker compose logs -f app
```
The first start runs the migrations, and can outlast the health check of the app container. If docker compose up -d reports that bpmn-app is unhealthy, see Troubleshooting. Do not go back to 1.0 while the application is still migrating.
If you upgraded from 1.0.0, install your license file again: sign in as an Admin, and upload the .lic file from the licenses-1.0.0 folder on the license page. See Manage the license.
Check the version, as described in Check the version.

Once you have checked that 1.1 works, you can remove the 1.0 image to free disk space, for example docker image rm process-designer:v1.0.2. With 1.0.0, remove the two tags of each of its two images:

docker image rm process-designer-backend:v1.0.0 process-designer-backend:latest process-designer-frontend:v1.0.0 process-designer-frontend:latest

Keep the 1.0 images as long as you might need to go back to 1.0.

For everything else about the Docker distribution, see Install with Docker.

Upgrade the standalone distribution

Prepare, while 1.0 still runs

If you upgrade from 1.0.0, install a Java 17 or newer runtime on the host. The 1.0.0 archive brought its own runtime; the 1.1 archive does not. See Standalone installation for how the start script finds Java.
Extract the 1.1 archive next to your 1.0 folder. It creates a process-designer-1.1.0-standalone/ folder, called the new folder below.
Copy your 1.0 config.env into the new folder, next to app.jar. Remove the variables that 1.1 no longer reads, such as BACKEND_PORT and LICENSE_BYPASS. config.env.example documents the new optional variables, such as JAVA_OPTS and the log file settings. A JAVA_OPTS line had no effect in 1.0.x and now applies: always include an -Xmx value in it.
Copy the licenses/ folder of your 1.0 folder into the new folder, next to app.jar, if your license file is stored there. This is the default location.
If you run Bonita Process Designer as a systemd service, edit WorkingDirectory and ExecStart in its unit file to point at the new folder. If you upgrade from 1.0.0 and Java is not on the default PATH, also add Environment=JAVA_HOME=<java-home> to the [Service] section: the start script looks for Java through JRE_HOME, then JAVA_HOME, then the PATH. Then run sudo systemctl daemon-reload. The service keeps running 1.0 until you restart it.

Stop 1.0 and back it up, once users have stopped working

Stop 1.0: press Ctrl+C in the terminal running the start script, or stop the service (sudo systemctl stop process-designer).

With 1.0.0 on Windows, Ctrl+C stops only the front-end: the back-end keeps running in the background. End it too. First find its process ID, in the last column of the LISTENING line that this command prints:

netstat -ano | findstr ":3000"

Then end that process, replacing <id> with its process ID:

taskkill /pid <id> /f

Finally, check that ports 3000 and 8080 are free: netstat -ano | findstr ":3000 :8080" must list no LISTENING line.

Back up the PostgreSQL database configured in config.env, with your usual tool, for example:
```
pg_dump -h <host> -p <port> -U <database-user> -Fc -f backup-1.0.dump <database>
pg_restore --list backup-1.0.dump
```
The second command reads the backup back: it must list the contents of the dump and end without an error.

Check the import logs. Migration V26 adds length limits to the import log table, as described for the Docker distribution. Run this query with psql against the database configured in config.env:

psql -h <host> -p <port> -U <database-user> -d <database> -c "SELECT count(*) FROM migration_entries WHERE char_length(element_id) > 255 OR char_length(original_type) > 255 OR char_length(reason) > 2000;"

If the count is not zero, delete those import log rows:

psql -h <host> -p <port> -U <database-user> -d <database> -c "DELETE FROM migration_entries WHERE char_length(element_id) > 255 OR char_length(original_type) > 255 OR char_length(reason) > 2000;"

Start 1.1

From the new folder, start 1.1: run ./start.sh on Linux and macOS, .\start.bat in Windows PowerShell or start.bat in cmd.exe, or restart the service. The first start runs the migrations.

Do not redirect the console into logs/ (for example ./start.sh > logs/app.log). 1.1 writes its own rotating log file there, logs/process-designer.log, and a redirected copy would never rotate. See Logs and log levels.

Check the version, as described in Check the version.

Check the version

1.1 is the first release that reports its own version: every 1.0.x version shows 1.0.0. After the upgrade, three places show 1.1.0:

the page footer, for example on the sign-in page (Process Designer · v1.1.0);
the /actuator/info endpoint, available to Admins only (see Finding the right URL);
the diagnostic archive that an Admin downloads from the Support tab of the admin panel.

Then sign in as an Admin. If the license page opens, no valid license is installed: see Manage the license.

What changes for your scripts

Review this table if you automate or monitor Bonita Process Designer, or if you wrote your own procedures around 1.0.x.

Change Upgrading from What to do

Change	Upgrading from	What to do
The application runs as a single `app` service (container `bpmn-app`). The `backend` and `frontend` services are gone.	Docker 1.0.0	Use `app` in your commands, for example `docker compose logs app` or `docker compose exec app <command>`.
Caddy forwards every path to the application, with no `/api` prefix: `https://<host>/api/settings` becomes `https://<host>/settings`.	Docker 1.0.0	Remove the `/api` prefix from the URLs of your scripts and monitoring probes.
One image, `process-designer:v1.1.0` in the archive, `bonitasoft.jfrog.io/docker/process-designer:1.1.0` in the Bonita Artifact Repository, replaces the `process-designer-backend` and `process-designer-frontend` images.	Docker 1.0.0	Load it with `install.sh` or `install.bat`, or pull it: see Get the application.
The license file is kept in the `bonita_licenses` volume.	Docker 1.0.0	Install the license file again after the upgrade. The `bonita_licenses` volume then keeps the file across later upgrades.
One Java process serves the editor and the API on `PORT` (8080 by default). Nothing listens on port 3000 any more, and `BACKEND_PORT` has no effect. The archive no longer includes a Java or a Node.js runtime.	Standalone 1.0.0	Point your scripts at port 8080 (or your `PORT`). If your own reverse proxy routes an `/api` path or port 3000 to the back-end, route everything to `PORT` instead, with no prefix. Install Java 17 or newer on the host.
The application writes its own rotating log file, `logs/process-designer.log`.	Standalone 1.0.x	Collect that file instead of a redirected console output. Do not redirect the console into `logs/`.
`LICENSE_BYPASS` is removed.	1.0.x	Remove it from your configuration, and install a valid license file.
The application runs with an explicit Java heap ceiling: `-Xmx192m` in the Docker image, `-Xmx512m` in the standalone distribution. `JAVA_OPTS` had no effect in 1.0.x; it now sets the options of the Java virtual machine.	1.0.x	If the log shows `OutOfMemoryError`, raise the ceiling with `JAVA_OPTS`. A `JAVA_OPTS` value replaces the default: always include an `-Xmx` value in it. In Docker, add `JAVA_OPTS=-Xmx512m` (for example) to the `environment:` of the `app` service in `docker-compose.yml`. In the standalone distribution, set `JAVA_OPTS` in `config.env`.
The `docker-compose.yml` of the 1.1 archive caps the container logs: 500 MB for `app`, 30 MB for each other service. The `app` container also keeps a copy of its log inside the container, bounded to 100 MB.	Docker 1.0.x	If you ship container logs to your own aggregator, adjust the `logging:` settings of the services. See Logs and log levels.
`docker-compose.yml` passes `LOG_LEVEL`, `LOG_LEVEL_ROOT` and `LOG_LEVEL_TOMCAT_HTTP` to the application.	Docker 1.0.x	Set them in the `.env` file or in the shell, instead of editing the Compose file.

The application runs as a single app service (container bpmn-app). The backend and frontend services are gone.

Docker 1.0.0

Use app in your commands, for example docker compose logs app or docker compose exec app <command>.

Caddy forwards every path to the application, with no /api prefix: https://<host>/api/settings becomes https://<host>/settings.

Docker 1.0.0

Remove the /api prefix from the URLs of your scripts and monitoring probes.

One image, process-designer:v1.1.0 in the archive, bonitasoft.jfrog.io/docker/process-designer:1.1.0 in the Bonita Artifact Repository, replaces the process-designer-backend and process-designer-frontend images.

Docker 1.0.0

Load it with install.sh or install.bat, or pull it: see Get the application.

The license file is kept in the bonita_licenses volume.

Docker 1.0.0

Install the license file again after the upgrade. The bonita_licenses volume then keeps the file across later upgrades.

One Java process serves the editor and the API on PORT (8080 by default). Nothing listens on port 3000 any more, and BACKEND_PORT has no effect. The archive no longer includes a Java or a Node.js runtime.

Standalone 1.0.0

Point your scripts at port 8080 (or your PORT). If your own reverse proxy routes an /api path or port 3000 to the back-end, route everything to PORT instead, with no prefix. Install Java 17 or newer on the host.

The application writes its own rotating log file, logs/process-designer.log.

Standalone 1.0.x

Collect that file instead of a redirected console output. Do not redirect the console into logs/.

LICENSE_BYPASS is removed.

1.0.x

Remove it from your configuration, and install a valid license file.

The application runs with an explicit Java heap ceiling: -Xmx192m in the Docker image, -Xmx512m in the standalone distribution. JAVA_OPTS had no effect in 1.0.x; it now sets the options of the Java virtual machine.

1.0.x

If the log shows OutOfMemoryError, raise the ceiling with JAVA_OPTS. A JAVA_OPTS value replaces the default: always include an -Xmx value in it. In Docker, add JAVA_OPTS=-Xmx512m (for example) to the environment: of the app service in docker-compose.yml. In the standalone distribution, set JAVA_OPTS in config.env.

The docker-compose.yml of the 1.1 archive caps the container logs: 500 MB for app, 30 MB for each other service. The app container also keeps a copy of its log inside the container, bounded to 100 MB.

Docker 1.0.x

If you ship container logs to your own aggregator, adjust the logging: settings of the services. See Logs and log levels.

docker-compose.yml passes LOG_LEVEL, LOG_LEVEL_ROOT and LOG_LEVEL_TOMCAT_HTTP to the application.

Docker 1.0.x

Set them in the .env file or in the shell, instead of editing the Compose file.

Log files written by 1.0.x can contain values that 1.1 no longer records at the default log level, such as a process title quoted in a database error or proxy credentials. After the upgrade, delete those files or restrict access to them.

What your users will notice

Tell your users about these changes before they sign in to 1.1:

Every existing diagram is at the top level, called Home. Folders are new in 1.1: nothing is filed automatically, so users file their diagrams themselves. See Organize existing processes into folders.
Diagram titles are no longer unique. Two processes can now have the same title, for example a "Validation" process in two departments. When a diagram calls two processes that have the same title, Bonita Studio links both Call Activities to one of them. Give called processes distinct titles before you export them to Bonita Studio. See Processes with the same name.
Save is reported only once the server has saved. The editor shows a Save as successful, and stops flagging unsaved changes, only after the server has confirmed the write. A failed Save keeps the changes flagged. During real-time editing, Save no longer sends the whole document, which could overwrite a co-editor’s changes: the server saves the shared document instead. See Save your work.
While no valid license is installed, every user is sent to the license page. Only an Admin can install the license file.

Go back to 1.0

Going back to 1.0 means restoring the backup taken before the upgrade. Every change made in 1.1 is lost.

Docker distribution

From the directory of the 1.1 docker-compose.yml, stop 1.1 with docker compose down (without -v).
From the directory of the 1.0 docker-compose.yml, start the database only, and copy the backup into it:
```
docker compose up -d postgres
docker compose cp ./backup-1.0.dump postgres:/tmp/backup-1.0.dump
```

Recreate an empty database.

This deletes the database migrated to 1.1, and every change made since the upgrade.

docker compose exec -T postgres dropdb -U postgres bpmnDB
docker compose exec -T postgres createdb -U postgres bpmnDB

Restore the backup. The command stops at the first error and, in that case, restores nothing:

docker compose exec -T postgres pg_restore -U postgres -d bpmnDB --exit-on-error --single-transaction /tmp/backup-1.0.dump

Start 1.0: docker compose up -d. The 1.0 image must still be loaded.
If you went back to 1.0.0, install the license file again from the licenses-1.0.0 folder, on the license page.

Standalone distribution

Stop 1.1: press Ctrl+C in the terminal running the start script, or stop the service.
Recreate an empty database, with the same name and the same owner, with your usual tool.

This deletes the database migrated to 1.1, and every change made since the upgrade.

Restore the backup. The command stops at the first error and, in that case, restores nothing:

pg_restore -h <host> -p <port> -U <database-user> -d <database> --exit-on-error --single-transaction backup-1.0.dump

Start 1.0 from its own folder. If you run it as a systemd service, point WorkingDirectory and ExecStart back at the 1.0 folder, then run sudo systemctl daemon-reload.