Installing ThingsBoard on Raspberry Pi

This guide walks you through installing ThingsBoard on a Raspberry Pi, from a clean environment to a fully running instance. By the end, you will have a licensed, activated ThingsBoard instance — free, no credit card required — with a system administrator account and, optionally, a demo tenant.

• Raspberry Pi with at least 4 GB of RAM
• Raspberry Pi OS (64-bit) based on Debian 13 “Trixie” — earlier releases do not provide the OpenJDK 25 packages
• A user account with sudo privileges
• Outbound internet access to download packages and to reach the ThingsBoard License Portal during activation

ThingsBoard runs on the Java Virtual Machine and requires Java 25. Install OpenJDK 25:

sudo apt update
sudo apt install -y openjdk-25-jdk-headless

Set OpenJDK 25 as the default Java version:

sudo update-alternatives --config java

Verify the installation:

java -version

The reported version must be 25.

Download the installation package:

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

Install ThingsBoard as a service:

sudo dpkg -i thingsboard-4.4.deb

Install PostgreSQL 16:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt update
sudo apt -y install postgresql-16
sudo service postgresql start

Set a password for the postgres user:

sudo -u postgres psql -c "\password"

Enter and confirm the password when prompted. Connect to PostgreSQL and create the ThingsBoard database:

psql -U postgres -d postgres -h 127.0.0.1 -W

CREATE DATABASE thingsboard;

Press Ctrl+D twice to exit.

Configure ThingsBoard to use PostgreSQL. Edit the configuration file:

sudo nano /etc/thingsboard/conf/thingsboard.conf

Add the following lines. Replace PUT_YOUR_POSTGRESQL_PASSWORD_HERE with your actual postgres password:

# DB Configuration
export DATABASE_TS_TYPE=sql
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/thingsboard
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=PUT_YOUR_POSTGRESQL_PASSWORD_HERE

ThingsBoard uses a message broker for internal communication between services. Choose one of the options below:

• In Memory — built-in, default. Suitable for development and PoC environments. Not recommended for production or cluster deployments.
• Confluent Cloud — fully managed streaming platform based on Kafka. Useful for cloud-agnostic deployments.

sudo nano /etc/thingsboard/conf/thingsboard.conf

export TB_QUEUE_TYPE=kafka
export TB_QUEUE_KAFKA_USE_CONFLUENT_CLOUD=true
export TB_KAFKA_SERVERS=localhost:9092
export TB_QUEUE_KAFKA_REPLICATION_FACTOR=3
export TB_QUEUE_KAFKA_CONFLUENT_SASL_JAAS_CONFIG='org.apache.kafka.common.security.plain.PlainLoginModule required username="CLUSTER_API_KEY" password="CLUSTER_API_SECRET";'
export TB_QUEUE_CORE_POLL_INTERVAL_MS=1000
export TB_QUEUE_CORE_PARTITIONS=2
export TB_QUEUE_RULE_ENGINE_POLL_INTERVAL_MS=1000
export TB_QUEUE_TRANSPORT_REQUEST_POLL_INTERVAL_MS=1000
export TB_QUEUE_TRANSPORT_RESPONSE_POLL_INTERVAL_MS=1000
export TB_QUEUE_TRANSPORT_NOTIFICATIONS_POLL_INTERVAL_MS=1000
export TB_QUEUE_VC_INTERVAL_MS=1000
export TB_QUEUE_VC_PARTITIONS=1

Raspberry Pi devices typically have limited RAM. Edit the ThingsBoard configuration file:

sudo nano /etc/thingsboard/conf/thingsboard.conf

Add or update the following environment variable. Set the value to half of your total RAM (e.g. 2G for a 4 GB Raspberry Pi):

export JAVA_OPTS="$JAVA_OPTS -Xms2G -Xmx2G"

Run the installation script to initialize the database schema:

sudo /usr/share/thingsboard/bin/install/install.sh

Start the ThingsBoard service:

sudo service thingsboard start

Open the required ports in your firewall so devices and users can reach the platform — expand the list below for the full set of ports and protocols.

Open ThingsBoard in a web browser:

http://localhost:8080

On first launch you are greeted with the activation screen:

Welcome to ThingsBoard 4.4.0
Get your free license and start building

Continue with the next step to license and activate your instance.

Opening ThingsBoard in your browser for the first time shows an activation welcome screen.

Once activated, ThingsBoard prompts you to create your System Administrator account — the account that manages the platform itself (tenants, system settings, platform-wide resources).

1. Enter Email, Password, and Confirm password.
2. The Set up a demo tenant option is selected by default: it creates a ready-made tenant with dashboards, devices, and rule chains for exploring the platform before building your own solution. Clear it if you want to start with an empty platform.
3. Click Create account. You are signed in as the system administrator.

Your ThingsBoard instance is now installed and running.

The WebReport service renders dashboards into PDF and PNG reports. Install it if you need scheduled or on-demand dashboard reports. Choose one of the installation methods below:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

nano tb-web-report.yml

version: '3.0'
services:
  tb-web-report:
    container_name: tb-web-report
    restart: always
    image: "thingsboard/tb-web-report:4.4.0"
    ports:
      - "8383:8383"
    env_file:
      - ./tb-web-report.env

nano tb-web-report.env

HTTP_BIND_ADDRESS=0.0.0.0
HTTP_BIND_PORT=8383
LOGGER_LEVEL=info
LOG_FOLDER=logs
LOGGER_FILENAME=tb-web-report-%DATE%.log
DOCKER_MODE=true
DEFAULT_PAGE_NAVIGATION_TIMEOUT=120000
DASHBOARD_IDLE_WAIT_TIME=3000
USE_NEW_PAGE_FOR_REPORT=true

docker compose -f tb-web-report.yml up -d

docker logs -f tb-web-report

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

sudo apt install -yq libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 \
     libexpat1 libfontconfig1 libgcc1 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 \
     libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 \
     libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 \
     ca-certificates fonts-liberation libnss3 lsb-release xdg-utils unzip wget libgbm-dev

sudo apt install -y fonts-roboto

sudo dpkg -i tb-web-report-4.4.deb
sudo service tb-web-report start

Check the service status:

sudo service thingsboard status

ThingsBoard logs are stored in /var/log/thingsboard. Check for errors:

cat /var/log/thingsboard/thingsboard.log | grep ERROR

Monitor logs in real time:

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

For more troubleshooting tips, see the Troubleshooting guide.

With ThingsBoard running, these concept guides help you build your first solution:

• Getting Started — a guided walkthrough of the platform after installation.
• Multi-Tenancy & Hierarchy — how tenants, customers, and users are organized.
• Digital Twin Model — how devices and assets are modeled in the platform.
• Data Processing — how the Rule Engine transforms and routes incoming data.
• Alarms & Notifications — how to detect conditions and notify users.
• Data Visualization — how to build dashboards and widgets.