Cluster setup using Docker Compose

This guide walks you through setting up ThingsBoard Professional Edition in cluster mode using Docker Compose with microservices architecture. Docker container images are available on Docker Hub.

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 PE images

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

Step 2. Clone ThingsBoard PE Docker Compose scripts

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

Step 3. Obtain and configure the license key

We assume you have already chosen your subscription plan or decided to purchase a perpetual license. If not, navigate to the pricing page to select the best license option for your case. See How to get a pay-as-you-go subscription or How to get a perpetual license for details.

Edit the ThingsBoard node environment file:

nano tb-node.env

Replace PUT_YOUR_LICENSE_SECRET_HERE with your actual license secret:

TB_LICENSE_SECRET=PUT_YOUR_LICENSE_SECRET_HERE

Step 4. Configure deployment type

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

nano .env

Set the TB_SETUP variable to one of the following:

Mode	Description
`basic` (recommended, default)	ThingsBoard Core and Rule Engine run in one JVM (requires 1 license). MQTT, CoAP, and HTTP transports run in separate containers.
`monolith`	ThingsBoard Core, Rule Engine, and all transports run in one JVM (requires 1 license). Minimizes memory footprint.
`advanced`	ThingsBoard Core and Rule Engine run in separate replicated containers (requires 4 licenses).

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

Step 5. 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 6. 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 7. 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 8. Enable Trendz Analytics (optional)

You may optionally install Trendz Analytics at any time.

Edit the .env file:

nano .env

Set TRENDZ_ENABLED to true:

TRENDZ_ENABLED=true

Step 9. 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 -f $TB_SETUP/docker-compose.yml logs -f tb-core1 tb-rule-engine1

View the state of all containers:

docker compose -f $TB_SETUP/docker-compose.yml ps

Stream logs of all services:

docker compose -f $TB_SETUP/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.

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.

Upgrading Trendz

Trendz Analytics has a different version system and should be updated separately from the ThingsBoard platform.

Edit the .env file and set TRENDZ_VERSION to the target version, then run:

./docker-stop-services.sh
./docker-upgrade-trendz.sh
./docker-start-services.sh

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.