Cluster setup using Docker Compose

This guide walks you through setting up ThingsBoard Community Edition in cluster mode using Docker Compose with microservices architecture.

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

Prerequisites

Install Docker:

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

Step 1. Pull ThingsBoard CE images

Make sure you have logged in to Docker Hub using the command line.

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

Step 2. Clone ThingsBoard CE repository

git clone -b release-4.3 https://github.com/thingsboard/thingsboard.git --depth 1
cd thingsboard/docker

Step 3. Configure database

Edit the .env file to set the database type:

nano .env

Set the DATABASE variable to one of:

Value	Description
`postgres`	Use PostgreSQL for all data
`hybrid`	Use PostgreSQL for entities and Cassandra for time-series data

Step 4. Choose queue service

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.

Kafka (recommended)
Confluent Cloud

Apache Kafka is an open-source stream-processing platform.

Edit the .env file:

nano .env

Verify the following line:

TB_QUEUE_TYPE=kafka

To use Confluent Cloud, first create an account, then create a Kafka cluster and obtain your API Key.

Edit the .env file:

nano .env

Set the queue type:

TB_QUEUE_TYPE=confluent

Configure the Confluent Cloud environment file. Replace CLUSTER_API_KEY, CLUSTER_API_SECRET, and confluent.cloud:9092 with your actual values:

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
TB_QUEUE_KAFKA_TA_TOPIC_PROPERTIES=retention.ms:604800000;segment.bytes:52428800;retention.bytes:1048576000
TB_QUEUE_KAFKA_NOTIFICATIONS_TOPIC_PROPERTIES=retention.ms:604800000;segment.bytes:52428800;retention.bytes:1048576000
TB_QUEUE_KAFKA_JE_TOPIC_PROPERTIES=retention.ms:604800000;segment.bytes:52428800;retention.bytes:104857600

TB_QUEUE_CORE_POLL_INTERVAL_MS=1000
TB_QUEUE_CORE_PARTITIONS=2
TB_QUEUE_RULE_ENGINE_POLL_INTERVAL_MS=1000
TB_QUEUE_TRANSPORT_REQUEST_POLL_INTERVAL_MS=1000
TB_QUEUE_TRANSPORT_RESPONSE_POLL_INTERVAL_MS=1000
TB_QUEUE_TRANSPORT_NOTIFICATIONS_POLL_INTERVAL_MS=1000
TB_QUEUE_VC_INTERVAL_MS=1000
TB_QUEUE_VC_PARTITIONS=1

You can update the default Rule Engine queue configuration using the UI. See Rule Engine Queues for details.

Step 5. Enable monitoring (optional)

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).

Step 6. Install and start ThingsBoard

Create host volumes

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

If you use Docker Desktop on macOS with Synchronized file shares (enabled by default for /Users subdirectories), skip the ownership change:

./docker-create-log-folders.sh --skipChown
./docker-check-log-folders.sh --skipChown

Run installation

./docker-install-tb.sh --loadDemo

The --loadDemo flag loads sample tenant account, dashboards, and devices for evaluation and testing.

Start services

./docker-start-services.sh

After a while when all services are started, open http://localhost in your browser. You should see the ThingsBoard login page. Use the following default credentials:

System Administrator: [email protected] / sysadmin
Tenant Administrator: [email protected] / tenant
Customer User: [email protected] / customer

You can change passwords for each account in the account profile page.

See Getting Started for your next steps after login.

Inspect logs and control containers

Stream ThingsBoard node logs:

docker compose logs -f tb-core1 tb-rule-engine1

View the state of all containers:

docker compose ps

Stream logs of all services:

docker compose 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.

Post-installation

Generate HTTPS certificate

The deployment uses HAProxy for proxying traffic to containers. By default ports 80 and 443 are used. To use HTTPS with a valid certificate:

docker exec haproxy-certbot certbot-certonly --domain your_domain --email your_email
docker exec haproxy-certbot haproxy-refresh

Upgrading

When a new ThingsBoard release becomes available, update your installation to benefit from the latest features and security patches.

See the Upgrade Instructions for detailed steps.

Troubleshooting

DNS issues

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.