Documentation for installation and configuration of ThingsBoard IoT Platform.

ThingsBoard Professional Edition cluster setup guide

This guide will help you to setup ThingsBoard in cluster mode. For this purpose, we will use docker container images available on Docker Hub.
For simplicity, we will use docker-compose tool to setup our cluster. You might use the same images with Docker Swarm, Kubernetes, OpenShift or other tools.


ThingsBoard Microservices are running in dockerized environment. Before starting please make sure Docker CE and Docker Compose are installed in your system.

Step 1. Checkout all ThingsBoard PE Images

Please checkout all ThingsBoard PE Images from Docker Hub. You will need to open all verified images and click on “Proceed to checkout” to accept ThingsBoard PE license agreement.

Listing all images mandatory for checkout for your convenience below:


Populate basic information about yourself and click “Get Content”


Step 2. Pull ThingsBoard PE Images

Make sure your have logged in to docker hub using command line.

docker pull store/thingsboard/tb-pe-node:2.4.0PE
docker pull store/thingsboard/tb-pe-web-ui:2.4.0PE
docker pull store/thingsboard/tb-pe-web-report:2.4.0PE
docker pull store/thingsboard/tb-pe-js-executor:2.4.0PE
docker pull store/thingsboard/tb-pe-http-transport:2.4.0PE
docker pull store/thingsboard/tb-pe-mqtt-transport:2.4.0PE
docker pull store/thingsboard/tb-pe-coap-transport:2.4.0PE

Step 3. Clone ThingsBoard PE Docker Compose scripts

git clone tb-pe-docker-compose

Step 4. Obtain your license key

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

IMPORTANT NOTE: Make sure you have purchased a license key for at least two instances of ThingsBoard PE. Otherwise you need to modify local copy of docker-compose.yml to use only one ThingsBoard instance. We will reference the license key you have obtained during this step as PUT_YOUR_LICENSE_SECRET_HERE later in this guide.

Step 5. Configure your license key

cd tb-pe-docker-compose
nano tb-node.env

and put the license secret parameter

# ThingsBoard server configuration



Step 6. Review the architecture page

Starting ThingsBoard v2.2, it is possible to install ThingsBoard cluster using new microservices architecture and docker containers. See microservices architecture page for more details.

Step 7. Installation

Before performing initial installation you can configure the type of database to be used with ThingsBoard. In order to set database type change the value of DATABASE variable in .env file to one of the following:

NOTE: According to the database type corresponding docker service will be deployed (see docker-compose.postgres.yml, docker-compose.cassandra.yml for details).

Execute the following command to run installation:

$ ./ --loadDemo


Step 8. Running

Execute the following command to start services:

$ ./

After a while when all services will be successfully started you can open http://{your-host-ip} in you browser (for ex. http://localhost). You should see ThingsBoard login page.

Use the following default credentials:

If you installed DataBase with demo data (using --loadDemo flag) you can also use the following credentials:

In case of any issues you can examine service logs for errors. For example to see ThingsBoard node logs execute the following command:

$ docker-compose logs -f tb1

Or use docker-compose ps to see the state of all the containers. Use docker-compose logs --f to inspect the logs of all running services. See docker-compose logs command reference for details.

Execute the following command to stop services:

$ ./

Execute the following command to stop and completely remove deployed docker containers:

$ ./

Execute the following command to update particular or all services (pull newer docker image and rebuild container):

$ ./ [SERVICE...]



In case when database upgrade is needed, execute the following commands:

$ ./
$ ./ --fromVersion=[FROM_VERSION]
$ ./


Next steps