ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform. Open documentation for releases before 2.0
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 and Cassandra as a NoSQL database. You can host Cassandra 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) and Zookeeper(2181).


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}"

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