Upgrading from Community Edition

Starting with ThingsBoard 4.4, Community Edition and Professional Edition are unified into a single platform that requires a license key.

This guide explains how to upgrade an existing Community Edition deployment to ThingsBoard 4.4.

Complete these steps first:

1. Upgrade to ThingsBoard CE 4.3.1.6 or later. Follow the CE upgrade instructions.
2. Get a license key. Register for the Community Grant Program to get a free perpetual key, or buy one in the License Portal. Make sure the license covers your current number of devices and assets.
3. Back up the database and configuration files. After the database upgrade you can’t roll back to Community Edition without this backup.

Use these instructions to upgrade an existing ThingsBoard Community Edition deployment installed from the .deb package on Ubuntu to ThingsBoard 4.4.

ThingsBoard 4.4 requires Java 25, while ThingsBoard Community Edition 4.3 runs on Java 17. Install OpenJDK 25 and make it the default Java version:

sudo apt update && sudo apt install -y openjdk-25-jdk-headless
sudo update-alternatives --set java /usr/lib/jvm/java-25-openjdk-$(dpkg --print-architecture)/bin/java

Verify the installation:

java -version

The reported version must be 25.

ThingsBoard 4.4 requires font libraries for its built-in reporting component. Community Edition doesn’t use them, so install them before the upgrade:

sudo apt update && sudo apt install -y libharfbuzz0b fontconfig fonts-dejavu-core

Download the ThingsBoard 4.4.0 package:

wget https://github.com/thingsboard/thingsboard/releases/download/v4.4/thingsboard-4.4.deb

Run the next steps from this directory so that the package file can be found.

Stop the ThingsBoard service so that the database isn’t in use during the upgrade:

sudo systemctl stop thingsboard

ThingsBoard stays unavailable until it starts again in Step 7, so plan the upgrade for a maintenance window.

Install the ThingsBoard 4.4.0 package over the existing Community Edition installation:

sudo dpkg -i thingsboard-4.4.deb

Run the upgrade script. It migrates the database schema and data from Community Edition to ThingsBoard 4.4:

sudo /usr/share/thingsboard/bin/install/upgrade.sh --fromVersion=CE

On large databases the script can take a long time. Don’t interrupt it.

Start the ThingsBoard service:

sudo systemctl start thingsboard

The first startup after the upgrade can take a few minutes. To follow its progress, watch the log, and press Ctrl+C to stop watching:

tail -f /var/log/thingsboard/thingsboard.log

Open ThingsBoard in your browser using the URL configured for your deployment. What happens next depends on how you got your license:

• You registered through the Community Grant Program. Enter the Community Grant license key you received during registration.
• You didn’t use the Community Grant Program. License your instance as described in the Ubuntu installation guide.

Log in with your existing Community Edition credentials and confirm that your devices, dashboards, and other data are available.

The WebReport component is a separate service that renders dashboards into PDF and PNG reports. If you need scheduled or on-demand dashboard reports, install it as described in the Ubuntu installation guide.

↑ Back to Deployment Options

Use these instructions to upgrade an existing ThingsBoard Community Edition deployment installed from the .rpm package on CentOS or RHEL to ThingsBoard 4.4.

ThingsBoard 4.4 requires Java 25, while ThingsBoard Community Edition 4.3 runs on Java 17. Install OpenJDK 25 and make it the default Java version:

sudo dnf install -y java-25-openjdk-headless
sudo update-alternatives --set java /usr/lib/jvm/java-25-openjdk/bin/java

Verify the installation:

java -version

The reported version must be 25.

ThingsBoard 4.4 requires font libraries for its built-in reporting component. Community Edition doesn’t use them, so install them before the upgrade:

sudo dnf install -y harfbuzz fontconfig dejavu-sans-fonts

Download the ThingsBoard 4.4.0 package:

wget https://github.com/thingsboard/thingsboard/releases/download/v4.4/thingsboard-4.4.rpm

Run the next steps from this directory so that the package file can be found.

Stop the ThingsBoard service so that the database isn’t in use during the upgrade:

sudo systemctl stop thingsboard

ThingsBoard stays unavailable until it starts again in Step 7, so plan the upgrade for a maintenance window.

Install the ThingsBoard 4.4.0 package over the existing Community Edition installation:

sudo rpm -Uvh thingsboard-4.4.rpm

Run the upgrade script. It migrates the database schema and data from Community Edition to ThingsBoard 4.4:

sudo /usr/share/thingsboard/bin/install/upgrade.sh --fromVersion=CE

On large databases the script can take a long time. Don’t interrupt it.

Start the ThingsBoard service:

sudo systemctl start thingsboard

The first startup after the upgrade can take a few minutes. To follow its progress, watch the log, and press Ctrl+C to stop watching:

tail -f /var/log/thingsboard/thingsboard.log

Open ThingsBoard in your browser using the URL configured for your deployment. What happens next depends on how you got your license:

• You registered through the Community Grant Program. Enter the Community Grant license key you received during registration.
• You didn’t use the Community Grant Program. License your instance as described in the CentOS/RHEL installation guide.

Log in with your existing Community Edition credentials and confirm that your devices, dashboards, and other data are available.

The WebReport component is a separate service that renders dashboards into PDF and PNG reports. If you need scheduled or on-demand dashboard reports, install it as described in the CentOS/RHEL installation guide.

↑ Back to Deployment Options

Use these instructions to upgrade an existing ThingsBoard Community Edition deployment on Windows to ThingsBoard 4.4.

ThingsBoard 4.4 requires Java 25, while ThingsBoard Community Edition 4.3 runs on Java 17. Download and install JDK 25 (for example, Eclipse Temurin 25) and make it the system’s default Java version.

Verify the installation:

java -version

The reported version must be 25.

Download the ThingsBoard installation archive for Windows: thingsboard-windows-4.4.zip.

Open Command Prompt as Administrator and stop the ThingsBoard service:

net stop thingsboard

Before replacing the installation files, make a copy of your current ThingsBoard configuration directory located in <ThingsBoard install dir>\conf (e.g. C:\thingsboard\conf).

Keep this backup until the upgrade is complete.

1. The thingsboard-windows-4.4.zip archive contains a top-level thingsboard folder. Extract it to the parent of your installation directory (e.g. C:\) so that it replaces C:\thingsboard, and choose to replace all existing files. Check that upgrade.bat is located directly in C:\thingsboard, not in a nested C:\thingsboard\thingsboard folder.
2. Open the new conf\thingsboard.yml and copy your custom settings into it from the backup you made in Step 4: database connection, ports, queue settings, and any other values you changed. Use the new file as the base, the same as on Linux, so new 4.4 settings are kept.

1. Open Command Prompt as Administrator and go to the ThingsBoard installation directory (e.g. C:\thingsboard):

   cd C:\thingsboard

2. Run the upgrade script:

   upgrade.bat --fromVersion=CE

Start the ThingsBoard service:

net start thingsboard

Open ThingsBoard in your browser using the URL configured for your deployment. What happens next depends on how you got your license:

• You registered through the Community Grant Program. Enter the Community Grant license key you received during registration.
• You didn’t use the Community Grant Program. License your instance as described in the Docker (Windows) installation guide.

Log in with your existing Community Edition credentials and confirm that your devices, dashboards, and other data are available.

↑ Back to Deployment Options

Use these instructions to upgrade an existing single-node ThingsBoard Community Edition deployment that runs in Docker to ThingsBoard 4.4.

Pull the ThingsBoard 4.4.0 and WebReport images:

docker pull thingsboard/tb-node:4.4.0
docker pull thingsboard/tb-web-report:4.4.0

Stop and remove the ThingsBoard CE service:

docker compose stop thingsboard-ce
docker compose rm -f thingsboard-ce

Update your docker-compose.yml according to the Docker installation guide. Make sure to change the image tag to 4.4.0, define the required volumes, and add the WebReport service.

Run the upgrade and start the services:

docker compose run --rm -e UPGRADE_TB=true -e FROM_VERSION="CE" thingsboard
docker compose up -d

Open ThingsBoard in your browser using the URL configured for your deployment. What happens next depends on how you got your license:

• You registered through the Community Grant Program. Enter the Community Grant license key you received during registration.
• You didn’t use the Community Grant Program. License your instance as described in the Docker installation guide.

Log in with your existing Community Edition credentials and confirm that your devices, dashboards, and other data are available.

↑ Back to Deployment Options

Use these instructions to upgrade an existing ThingsBoard Community Edition cluster deployed with the Docker Compose scripts to ThingsBoard 4.4.

Pull the ThingsBoard 4.4.0 and WebReport images:

docker pull thingsboard/tb-node:4.4.0
docker pull thingsboard/tb-web-report:4.4.0

Stop the CE services:

./docker-stop-services.sh

Manually merge your current ThingsBoard CE cluster configuration with the default Docker Compose cluster deployment files. Ensure that you transfer all custom environment variables, volume mappings, and external service configurations to the new files.

Run the upgrade and start the services:

./docker-upgrade-tb.sh --fromVersion=CE
./docker-start-services.sh

Open ThingsBoard in your browser using the URL configured for your deployment. What happens next depends on how you got your license:

• You registered through the Community Grant Program. Enter the Community Grant license key you received during registration.
• You didn’t use the Community Grant Program. License your instance as described in the Docker Compose cluster setup guide.

Log in with your existing Community Edition credentials and confirm that your devices, dashboards, and other data are available.

↑ Back to Deployment Options

Use these instructions to upgrade an existing ThingsBoard Community Edition deployment on a Minikube Kubernetes cluster to ThingsBoard 4.4.

For AWS EKS, Azure AKS, or GCP GKE refer to the corresponding installation guides.

Delete the CE resources from the cluster:

./k8s-delete-resources.sh

ThingsBoard uses a separate repository of Kubernetes scripts with additional components. Clone it into a separate directory:

git clone -b release-4.4.0 https://github.com/thingsboard/thingsboard-pe-k8s.git --depth 1
cd thingsboard-pe-k8s/minikube

Copy your custom settings from the CE configuration (database type, hosts, environment variables, volumes) into the corresponding files of the new scripts.

Upgrade the Community Edition database:

./k8s-upgrade-tb.sh --fromVersion=CE

Deploy the ThingsBoard resources:

./k8s-deploy-resources.sh

Wait until all pods are running:

kubectl get pods -n thingsboard

The ThingsBoard URL is http://{your-cluster-ip}. Get the cluster IP with minikube ip.

Open ThingsBoard in your browser using the URL configured for your deployment. What happens next depends on how you got your license:

• You registered through the Community Grant Program. Enter the Community Grant license key you received during registration.
• You didn’t use the Community Grant Program. License your instance as described in the Minikube cluster setup guide.

Log in with your existing Community Edition credentials and confirm that your devices, dashboards, and other data are available.

↑ Back to Deployment Options