Documentation for installation and configuration of ThingsBoard IoT Platform.

Cluster setup

This guide will help you to setup ThingsBoard in cluster mode. There are two options available.

Starting ThingsBoard v2.2, it is possible to install ThingsBoard cluster using new microservices architecture and docker containers. See microservices architecture page and deployment tips for more details how to launch the ThingsBoard cluster in a “dockerized” environment. This option is recommended for advanced users only.

Cluster setup using monolithic architecture (before v2.2)

Installing cluster of monolithic ThingsBoard applications where each one contains all necessary transport and core components in a single VM is no longer recommended option. However, you may still want to use this option in case you would like to minimize amount of third-party used. See instructions below.


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}"
  # Cassandra cluster connection query parameters  #
    read_consistency_level: "${CASSANDRA_READ_CONSISTENCY_LEVEL:QUORUM}"
    write_consistency_level: "${CASSANDRA_WRITE_CONSISTENCY_LEVEL:QUORUM}"
  # 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:

Next steps