Skip to content
 
Try for free

ThingsBoard Cloud

Choose your data region

Your data stays in the region you choose, for residency and compliance. No credit card required.

North America Data stored in North America Europe Data stored in the European Union

Rather run it yourself? Install on your own servers

Installing ThingsBoard on Ubuntu Server

This guide covers installing ThingsBoard on Ubuntu Server, 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.

Prerequisites

Section titled “Prerequisites”
  • Ubuntu 22.04 LTS / 24.04 LTS / 26.04 LTS
  • A user account with sudo privileges
  • Outbound internet access to download packages and to reach the ThingsBoard License Portal during activation

Ensure your server meets the minimum requirements:

Use case CPU RAM Storage Recommended services
Development / PoC 1 core 4 GB 20 GB ThingsBoard, PostgreSQL
Production (small) 2 cores 8 GB 50 GB SSD ThingsBoard, PostgreSQL, Kafka
Production (recommended) 4+ cores 16+ GB 100+ GB SSD ThingsBoard, PostgreSQL, Kafka, Cassandra

Step 1. Install Java (OpenJDK)

Section titled “Step 1. Install Java (OpenJDK)”

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

Terminal window
sudo apt update && sudo apt install -y openjdk-25-jdk-headless

Set OpenJDK 25 as the default Java version. Use the non-interactive command:

Terminal window
sudo update-alternatives --set java /usr/lib/jvm/java-25-openjdk-$(dpkg --print-architecture)/bin/java

If you have multiple Java versions installed and prefer to choose interactively:

Terminal window
sudo update-alternatives --config java

Verify the installation:

Terminal window
java -version

The reported version must be 25.

Step 2. Install ThingsBoard Package

Section titled “Step 2. Install ThingsBoard Package”

Install the font libraries required by the built-in reporting component:

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

Download and install the ThingsBoard 4.4.0 package:

Terminal window
wget https://github.com/thingsboard/thingsboard/releases/download/v4.4/thingsboard-4.4.deb
sudo dpkg -i thingsboard-4.4.deb

Verify the installation:

Terminal window
dpkg -l thingsboard

The package appears in the output with the status ii.

Step 3. Configure Database

Section titled “Step 3. Configure Database”

ThingsBoard stores two kinds of data: entities (devices, assets, dashboards, users) and time-series telemetry. Choose the database configuration that matches your expected load:

  • PostgreSQL only — stores all data (entities and time-series) in PostgreSQL. Recommended for most deployments handling up to 5,000 messages per second. Simple to operate with minimal infrastructure requirements.
  • Hybrid (PostgreSQL + Cassandra) — stores entities in PostgreSQL and time-series data in Cassandra. Designed for high-throughput deployments exceeding 5,000 messages per second or with millions of devices. Requires significant additional resources: at least 8 GB RAM, a dedicated multi-core CPU, and fast SSD storage for the Cassandra node.

Install PostgreSQL 18:

Terminal window
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt update && sudo apt -y install postgresql-18
sudo systemctl start postgresql

Export your PostgreSQL password as an environment variable — this value will be used in the following steps:

Terminal window
TB_DB_PASSWORD=YOUR_PASSWORD

Set the password for the postgres user and create the ThingsBoard database:

Terminal window
sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD '$TB_DB_PASSWORD';"
Terminal window
sudo -u postgres psql -c "CREATE DATABASE thingsboard;"

Add the database configuration to the ThingsBoard configuration file:

Terminal window
sudo tee -a /etc/thingsboard/conf/thingsboard.conf > /dev/null << EOF
# 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=$TB_DB_PASSWORD
EOF

Step 4. Choose Queue Service

Section titled “Step 4. Choose Queue Service”

ThingsBoard uses a message queue to route messages between its internal services. Select the option that matches your infrastructure:

  • In Memory (default) — built-in queue, no extra setup required. Suitable for development and PoC. Not recommended for production or multi-node deployments.
  • Kafka — high-throughput, durable queue. Run it yourself or use a managed service such as AWS MSK.
  • Confluent Cloud — fully managed Kafka service. Use this if you want Kafka without managing the infrastructure yourself.

The In Memory queue is built in and enabled by default. No configuration is required.

Step 5. [Optional] Memory Configuration

Section titled “Step 5. [Optional] Memory Configuration”

By default, ThingsBoard sets no explicit memory limit — the JVM can consume all available RAM, which may cause the OS to kill the process under memory pressure. On smaller machines, set the maximum heap size explicitly. The values below are approximate and suited for a single-node setup with In Memory queue and PostgreSQL database:

Terminal window
sudo tee -a /etc/thingsboard/conf/thingsboard.conf > /dev/null << 'EOF'
# Maximum heap size — set to half of available RAM.
# Example: 2G for a 4 GB server, 4G for an 8 GB server, 8G for a 16 GB server.
export JAVA_OPTS="$JAVA_OPTS -Xms4G -Xmx4G -Xss512k -XX:+AlwaysPreTouch"
EOF

We recommend adjusting these parameters depending on your server resources. Set it to at least 2G (gigabytes), and increase it if there is additional RAM available. Use half of your total RAM if you do not run any other memory-intensive processes (e.g. Cassandra), or one third otherwise.

Step 6. Run Installation Script

Section titled “Step 6. Run Installation Script”

Run the installation script to initialize the database schema:

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

Step 7. Start ThingsBoard

Section titled “Step 7. Start ThingsBoard”

Start the ThingsBoard service:

Terminal window
sudo systemctl start thingsboard

Monitor the startup. The line confirming the platform is ready will be highlighted:

Terminal window
tail -f /var/log/thingsboard/thingsboard.log | grep --line-buffered --color=always -E 'Started ThingsboardServerApplication|$'

Configure Firewall

Section titled “Configure Firewall”

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.

Full port list
PortProtocolDescription
8080TCPWeb UI and REST API. Not required if using a load balancer.
1883TCPMQTT
8883TCPMQTT over SSL
5683UDPCoAP
5684UDPCoAP over DTLS
5685UDPLwM2M CoAP
5686UDPLwM2M CoAP over DTLS
5687UDPLwM2M (Bootstrap)
5688UDPLwM2M over DTLS (Bootstrap)
161UDPSNMP
7070TCPEdge RPC (gRPC)
9090TCPRemote Integration Executor (gRPC)

Access ThingsBoard Web UI

Section titled “Access ThingsBoard Web UI”

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.

Step 8. License and Activate Your Instance

Section titled “Step 8. License and Activate Your Instance”

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

  1. Click Open the License Portal, then create an account or sign in.
  2. Choose a free license: Commercial (up to 100 devices, one server) or Non-commercial (up to 1,000 devices, any number of servers).
  3. Check the confirmation box to agree to the Terms of Use, Privacy Policy, and ThingsBoard License (BUSL 1.1), then click Accept and activate to issue the license and activate your instance.
  4. Click Continue setup on your instance to proceed to account creation. Your license key stays available on this screen and in your License Portal account.

Step 9. Create Your Administrator Account

Section titled “Step 9. Create Your Administrator Account”

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.

[Optional] Install ThingsBoard WebReport Component

Section titled “[Optional] Install ThingsBoard WebReport Component”

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:

Install Docker: see Docker for Ubuntu.

Create the Docker Compose file ~/thingsboard/tb-web-report.yml:

Terminal window
mkdir -p ~/thingsboard
Terminal window
sudo tee ~/thingsboard/tb-web-report.yml > /dev/null << 'EOF'
services:
  tb-web-report:
    container_name: tb-web-report
    restart: always
    image: "thingsboard/tb-web-report:4.4.0"
    ports:
      - "8383:8383"
    environment:
      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"
EOF

Start the WebReport service:

Terminal window
docker compose -f ~/thingsboard/tb-web-report.yml up -d

Check the container logs:

Terminal window
docker logs -f tb-web-report

[Optional] Configure HTTPS

Section titled “[Optional] Configure HTTPS”

Serving ThingsBoard over HTTPS encrypts the traffic between browsers and the server and prevents browser security warnings. HTTPS is handled by HAProxy: it accepts incoming traffic on ports 80 (HTTP) and 443 (HTTPS), terminates TLS with a trusted certificate from Let’s Encrypt, and forwards requests to ThingsBoard.

Before you start, make sure that:

  • a domain name is assigned to your server, and its DNS record points to the server’s IP address;
  • ports 80 and 443 are reachable from the internet.

Follow Configure HAProxy on Ubuntu to install HAProxy and generate the certificate.

Troubleshooting

Section titled “Troubleshooting”

Check the service status:

Terminal window
sudo systemctl status thingsboard

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

Terminal window
grep ERROR /var/log/thingsboard/thingsboard.log

Monitor logs in real time:

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

Or follow the service log through journald:

Terminal window
sudo journalctl -u thingsboard.service -f --no-pager

For more troubleshooting tips, see the Troubleshooting guide.

Next Steps

Section titled “Next Steps”

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

© 2026 The ThingsBoard Authors