Cluster setup using Docker Compose

This guide walks you through setting up ThingsBoard in cluster mode using Docker Compose with microservices architecture. Licensing is free and requires no credit card. Docker container images are available on Docker Hub.

For a simpler single-node installation, see Docker (Linux, macOS).

Install Docker:

• Docker for Ubuntu
• Docker for CentOS
• Docker Desktop for macOS

A server with at least 8 GB of RAM (16 GB recommended for production cluster deployments).

You’ll also need outbound internet access to pull Docker images and to reach the ThingsBoard License Portal during activation.

docker pull thingsboard/tb-node:4.4.0
docker pull thingsboard/tb-web-report:4.4.0
docker pull thingsboard/tb-web-ui:4.4.0
docker pull thingsboard/tb-js-executor:4.4.0
docker pull thingsboard/tb-http-transport:4.4.0
docker pull thingsboard/tb-mqtt-transport:4.4.0
docker pull thingsboard/tb-coap-transport:4.4.0
docker pull thingsboard/tb-lwm2m-transport:4.4.0
docker pull thingsboard/tb-snmp-transport:4.4.0
docker pull thingsboard/tb-integration-executor:4.4.0

git clone -b release-4.4 https://github.com/thingsboard/thingsboard-pe-docker-compose.git tb-pe-docker-compose --depth 1
cd tb-pe-docker-compose

The docker compose scripts support three deployment modes. Edit the .env file:

nano .env

Set the TB_SETUP variable to one of the following:

All deployment modes support separate JS executors, Redis, and different queue services.

Edit the .env file to set the database type:

nano .env

Set the DATABASE variable to one of:

ThingsBoard cluster deployments require an external message broker. In Memory queue is not suitable for cluster mode.

• Kafka — recommended for production. Used on most ThingsBoard production environments. Works for on-prem and private cloud deployments.
• Confluent Cloud — fully managed streaming platform based on Kafka. Useful for cloud-agnostic deployments.

nano .env

TB_QUEUE_TYPE=kafka

nano .env

TB_QUEUE_TYPE=confluent

nano queue-confluent-cloud.env

TB_QUEUE_TYPE=kafka

TB_KAFKA_SERVERS=confluent.cloud:9092
TB_QUEUE_KAFKA_REPLICATION_FACTOR=3

TB_QUEUE_KAFKA_USE_CONFLUENT_CLOUD=true
TB_QUEUE_KAFKA_CONFLUENT_SSL_ALGORITHM=https
TB_QUEUE_KAFKA_CONFLUENT_SASL_MECHANISM=PLAIN
TB_QUEUE_KAFKA_CONFLUENT_SASL_JAAS_CONFIG='org.apache.kafka.common.security.plain.PlainLoginModule required username="CLUSTER_API_KEY" password="CLUSTER_API_SECRET";'
TB_QUEUE_KAFKA_CONFLUENT_SECURITY_PROTOCOL=SASL_SSL
TB_QUEUE_KAFKA_CONFLUENT_USERNAME=CLUSTER_API_KEY
TB_QUEUE_KAFKA_CONFLUENT_PASSWORD=CLUSTER_API_SECRET

TB_QUEUE_KAFKA_RE_TOPIC_PROPERTIES=retention.ms:604800000;segment.bytes:52428800;retention.bytes:1048576000
TB_QUEUE_KAFKA_CORE_TOPIC_PROPERTIES=retention.ms:604800000;segment.bytes:52428800;retention.bytes:1048576000

Edit the .env file:

nano .env

Set MONITORING_ENABLED to true:

MONITORING_ENABLED=true

After deployment, Prometheus will be available at http://localhost:9090 and Grafana at http://localhost:3000 (default login: admin / foobar).

You may optionally install Trendz Analytics at any time.

Edit the .env file:

nano .env

Set TRENDZ_ENABLED to true:

TRENDZ_ENABLED=true

Create log folders for the services. The script requires sudo permissions to change ownership:

./docker-create-log-folders.sh

Verify that all required volume folders are available and have correct ownership:

./docker-check-log-folders.sh

./docker-install-tb.sh

./docker-start-services.sh

After a while when all services are started, open ThingsBoard in a web browser:

http://localhost

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.

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.

The deployment already includes HAProxy as the haproxy-certbot container, so you only need to request the certificate. Replace YOUR_DOMAIN and YOUR_EMAIL with your values, then request the certificate and reload HAProxy to apply it:

docker exec haproxy-certbot certbot-certonly --domain YOUR_DOMAIN --email YOUR_EMAIL
docker exec haproxy-certbot haproxy-refresh

Run these commands from the repository root. Pick the tab that matches the TB_SETUP value in your .env file:

docker compose --env-file .env -f basic/docker-compose.yml logs -f tb-monolith | grep --line-buffered --color=always -E 'Started ThingsboardServerApplication|$'

docker compose --env-file .env -f basic/docker-compose.yml ps

docker compose --env-file .env -f basic/docker-compose.yml logs -f

docker compose --env-file .env -f monolith/docker-compose.yml logs -f tb-monolith | grep --line-buffered --color=always -E 'Started ThingsboardServerApplication|$'

docker compose --env-file .env -f monolith/docker-compose.yml ps

docker compose --env-file .env -f monolith/docker-compose.yml logs -f

docker compose --env-file .env -f advanced/docker-compose.yml logs -f tb-core1 tb-core2 tb-rule-engine1 tb-rule-engine2

docker compose --env-file .env -f advanced/docker-compose.yml ps

docker compose --env-file .env -f advanced/docker-compose.yml logs -f

Stop all services:

./docker-stop-services.sh

Remove all deployed containers:

./docker-remove-services.sh

Update specific services (pull newer image and rebuild container):

./docker-update-service.sh [SERVICE...]

If [SERVICE...] is omitted, all services are updated.

If you observe errors related to DNS issues, for example:

127.0.1.1:53: cannot unmarshal DNS message

Configure your system to use Google public DNS servers. See Linux and macOS instructions.

Inside a container, localhost and 127.0.0.1 point to the container itself, not to the Docker host. A ThingsBoard container reaches a PostgreSQL instance installed on the host through a different address.

Set the database address

The value of SPRING_DATASOURCE_URL depends on where PostgreSQL runs:

On macOS, Docker Desktop resolves host.docker.internal to the host automatically. On Linux, map the alias to the host gateway in every ThingsBoard service that connects to the database:

services:
  tb-core1:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Allow the Docker subnet in PostgreSQL

A PostgreSQL instance running on the host accepts local connections only until you configure it otherwise. Find the subnet of your Docker network first:

docker network ls
docker network inspect NETWORK_NAME --format '{{(index .IPAM.Config 0).Subnet}}'

Set the listen address in postgresql.conf:

listen_addresses = '*'

Add a matching client entry to pg_hba.conf. The database and user must match SPRING_DATASOURCE_URL and SPRING_DATASOURCE_USERNAME, and the subnet must be the one you found. The authentication method must match how the password is stored, so use md5 instead of scram-sha-256 on instances that still store MD5 passwords:

host    thingsboard    DB_USER    172.18.0.0/16    scram-sha-256

Restart PostgreSQL. A reload is enough for pg_hba.conf, but listen_addresses is applied at server start only:

sudo systemctl restart postgresql

Verify the connection

Run psql from a temporary container. It takes the same network path as ThingsBoard, which separates a networking problem from a ThingsBoard configuration problem. Replace DB_USER and DB_PASSWORD with the values from SPRING_DATASOURCE_USERNAME and SPRING_DATASOURCE_PASSWORD:

docker run --rm --add-host=host.docker.internal:host-gateway postgres:18 \
  psql "postgresql://DB_USER:DB_PASSWORD@host.docker.internal:5432/thingsboard" -c "SELECT 1;"

If this command succeeds and ThingsBoard still fails, the network path is fine and the problem is in the ThingsBoard configuration.

Check for a host firewall

Docker maps its internal networks to the host with iptables rules. Additional firewall software can interfere with those rules and drop the traffic before it reaches PostgreSQL. If connections time out instead of being rejected, check whether a firewall like UFW or firewalld is installed and enabled on the host, and whether its configuration blocks traffic coming from the Docker networks.

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.