ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform.
ThingsBoard Professional Edition with White-labeling and Platform Integrations Learn More

Cluster setup

This guide will help you to setup ThingsBoard in cluster mode.


ThingsBoard requires Zookeeper for cluster coordination, Cassandra as a NoSQL database and Redis for cluster cache. You can host Cassandra and Redis on the same nodes where you install ThingsBoard or on separate nodes.

We assume following topology


In this case, both Zookeeper and Cassandra nodes are deployed in cluster mode. We use two nodes clusters only for demonstration purposes. This is not recommended for production.

Let’s assume following hostnames:

We will use default ports for Cassandra (9042), Zookeeper(2181) and Redis(6379).


You can install ThingsBoard services using single node installation guide Please note that you don’t need to execute “Provision database schema and initial data” step only once per cluster.


You will need to change following Zookeeper and Cassandra parameters in thingsboard.yml

  enabled: "${ZOOKEEPER_ENABLED:true}"
  url: "${ZOOKEEPER_URL:zk1:2181,zk2:2181}"

  url: "${CASSANDRA_URL:c1:9042,c2:9042}"

  # standalone or cluster
    type: standalone
    host: "${REDIS_HOST:localhost}"
    port: "${REDIS_PORT:6379}"
    db: "${REDIS_DB:0}"
    password: "${REDIS_PASSWORD:}"

Also, you need to specify rpc.bind_host to match your current host for each thingsboard server. For example, tb1 configuration:

  bind_host: "${RPC_HOST:tb1}"


Following ports need to be accessible within cluster for corresponding servers:

Following ThingsBoard server ports need to be accessible outside cluster for device connectivity:

Load Balancing

Next steps