Installing ThingsBoard on CentOS/RHEL

This guide covers installing ThingsBoard on CentOS/RHEL 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.

• RHEL 9, CentOS Stream 9, or derivatives (AlmaLinux, Rocky Linux, Oracle Linux, etc.). ThingsBoard requires Java 25, and the java-25-openjdk packages ship with RHEL 9.7 and newer.
• 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:

Install required tools:

sudo dnf install -y wget
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm

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

sudo dnf install -y java-25-openjdk-headless

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

sudo update-alternatives --set java /usr/lib/jvm/java-25-openjdk/bin/java

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

sudo update-alternatives --config java

Verify the installation:

java -version

The reported version must be 25.

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

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

Download and install the ThingsBoard 4.4.0 package:

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

Verify the installation:

rpm -qa | grep thingsboard

The installed package is listed in the output.

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.

sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm

sudo dnf -qy module disable postgresql
sudo dnf -y install postgresql18 postgresql18-server postgresql18-contrib
sudo /usr/pgsql-18/bin/postgresql-18-setup initdb
sudo systemctl enable --now postgresql-18

TB_DB_PASSWORD=YOUR_PASSWORD

sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD '$TB_DB_PASSWORD';"

sudo -u postgres psql -c "CREATE DATABASE thingsboard;"

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

sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm

sudo dnf -qy module disable postgresql
sudo dnf -y install postgresql18 postgresql18-server postgresql18-contrib
sudo /usr/pgsql-18/bin/postgresql-18-setup initdb
sudo systemctl enable --now postgresql-18

TB_DB_PASSWORD=YOUR_PASSWORD

sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD '$TB_DB_PASSWORD';"

sudo -u postgres psql -c "CREATE DATABASE thingsboard;"

sudo rpm --import https://downloads.apache.org/cassandra/KEYS
sudo tee /etc/yum.repos.d/cassandra.repo > /dev/null <<'EOF'
[cassandra]
name=Apache Cassandra
baseurl=https://redhat.cassandra.apache.org/50x/
gpgcheck=1
repo_gpgcheck=0
gpgkey=https://downloads.apache.org/cassandra/KEYS
EOF
sudo dnf -y update && sudo dnf -y install cassandra cassandra-tools chkconfig
sudo systemctl daemon-reexec
sudo systemctl start cassandra.service
sudo chkconfig cassandra on

nodetool status

sudo tee -a /etc/thingsboard/conf/thingsboard.conf > /dev/null << EOF
# DB Configuration
export DATABASE_TS_TYPE=cassandra
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/thingsboard
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=$TB_DB_PASSWORD
EOF

export CASSANDRA_CLUSTER_NAME="Thingsboard Cluster"
export CASSANDRA_KEYSPACE_NAME=thingsboard
export CASSANDRA_URL=127.0.0.1:9042
export CASSANDRA_USE_CREDENTIALS=false
export CASSANDRA_USERNAME=
export CASSANDRA_PASSWORD=

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.

mkdir -p ~/thingsboard

sudo tee ~/thingsboard/docker-compose-kafka.yml > /dev/null << 'EOF'
services:
  kafka:
    restart: always
    image: bitnamilegacy/kafka:4.0
    ports:
      - 9092:9092
      - 9093
      - 9094
    environment:
      ALLOW_PLAINTEXT_LISTENER: "yes"
      KAFKA_CFG_LISTENERS: "OUTSIDE://:9092,CONTROLLER://:9093,INSIDE://:9094"
      KAFKA_CFG_ADVERTISED_LISTENERS: "OUTSIDE://localhost:9092,INSIDE://kafka:9094"
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "INSIDE:PLAINTEXT,OUTSIDE:PLAINTEXT,CONTROLLER:PLAINTEXT"
      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "INSIDE"
      KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE: "false"
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
      KAFKA_CFG_PROCESS_ROLES: "controller,broker"
      KAFKA_CFG_NODE_ID: "0"
      KAFKA_CFG_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
      KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: "0@kafka:9093"
    volumes:
      - kafka-data:/bitnami
volumes:
  kafka-data:
    driver: local
EOF

docker compose -f ~/thingsboard/docker-compose-kafka.yml up -d

sudo tee -a /etc/thingsboard/conf/thingsboard.conf > /dev/null << 'EOF'
export TB_QUEUE_TYPE=kafka
export TB_KAFKA_SERVERS=localhost:9092
EOF

sudo tee -a /etc/thingsboard/conf/thingsboard.conf > /dev/null << 'EOF'
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
EOF

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:

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.

Run the installation script to initialize the database schema:

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

Start the ThingsBoard service:

sudo systemctl start thingsboard

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

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

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:

mkdir -p ~/thingsboard

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

docker compose -f ~/thingsboard/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.rpm

sudo dnf install -y pango.x86_64 libXcomposite.x86_64 libXcursor.x86_64 libXdamage.x86_64 libXext.x86_64 libXi.x86_64 libXtst.x86_64 cups-libs.x86_64 libXScrnSaver.x86_64 libXrandr.x86_64 GConf2.x86_64 alsa-lib.x86_64 atk.x86_64 gtk3.x86_64 ipa-gothic-fonts xorg-x11-fonts-100dpi xorg-x11-fonts-75dpi xorg-x11-utils xorg-x11-fonts-cyrillic xorg-x11-fonts-Type1 xorg-x11-fonts-misc unzip nss

sudo dnf install -y google-roboto-fonts

sudo rpm -Uvh tb-web-report-4.4.rpm
sudo systemctl start tb-web-report

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 CentOS/RHEL to install HAProxy and generate the certificate.

Check the service status:

sudo systemctl status thingsboard

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

grep ERROR /var/log/thingsboard/thingsboard.log

Monitor logs in real time:

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

Or follow the service log through journald:

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

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.