Installing ThingsBoard PE using Docker (Linux or Mac OS)

Prerequisites
Step 1. Pull ThingsBoard PE Image
Step 2. Obtain the license key
Step 3. Choose ThingsBoard queue service
Step 4. Running
Detaching, stop and start commands
Troubleshooting
Next steps

This guide will help you to install and start ThingsBoard Professional Edition (PE) using Docker and Docker Compose on Linux or Mac OS. This guide covers standalone ThingsBoard PE installation. If you are looking for a cluster installation instruction, please visit cluster setup page.

Prerequisites

Install Docker:

Step 1. Pull ThingsBoard PE Image

docker pull thingsboard/tb-pe:3.5.1PE

Step 2. Obtain the 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.

Note: We will reference the license key you have obtained during this step as PUT_YOUR_LICENSE_SECRET_HERE later in this guide.

Step 3. Choose ThingsBoard queue service

ThingsBoard is able to use various messaging systems/brokers for storing the messages and communication between ThingsBoard services. How to choose the right queue implementation?

In Memory queue implementation is built-in and default. It is useful for development(PoC) environments and is not suitable for production deployments or any sort of cluster deployments.
Kafka is recommended for production deployments. This queue is used on the most of ThingsBoard production environments now. It is useful for both on-prem and private cloud deployments. It is also useful if you like to stay independent from your cloud provider. However, some providers also have managed services for Kafka. See AWS MSK for example.
RabbitMQ is recommended if you don’t have much load and you already have experience with this messaging system.
AWS SQS is a fully managed message queuing service from AWS. Useful if you plan to deploy ThingsBoard on AWS.
Google Pub/Sub is a fully managed message queuing service from Google. Useful if you plan to deploy ThingsBoard on Google Cloud.
Azure Service Bus is a fully managed message queuing service from Azure. Useful if you plan to deploy ThingsBoard on Azure.
Confluent Cloud is a fully managed streaming platform based on Kafka. Useful for a cloud agnostic deployments.

See corresponding architecture page and rule engine page for more details.

In Memory (built-in and default)

AWS SQS (managed service from AWS)

Google Pub/Sub (managed service from Google)

Azure Service Bus (managed service from Azure)

RabbitMQ (for small on-prem installations)

Confluent Cloud (Event Streaming Platform based on Kafka)

ThingsBoard includes In Memory Queue service and use it by default without extra settings.

Create docker compose file for ThingsBoard queue service:

nano docker-compose.yml

Add the following line to the yml file. Don’t forget to replace “PUT_YOUR_LICENSE_SECRET_HERE” with your license secret obtained on the first step:

version: '3.0'
services:
  mytbpe:
    restart: always
    image: "thingsboard/tb-pe:3.5.1PE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    environment:
      TB_QUEUE_TYPE: in-memory
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      TB_LICENSE_SECRET: PUT_YOUR_LICENSE_SECRET_HERE
      TB_LICENSE_INSTANCE_DATA_FILE: /data/license.data
    volumes:
      - ~/.mytbpe-data:/data
      - ~/.mytbpe-logs:/var/log/thingsboard
  postgres:
    restart: always
    image: "postgres:12"
    ports:
    - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - ~/.mytbpe-data/db:/var/lib/postgresql/data

Apache Kafka is an open-source stream-processing software platform.

Create docker compose file for ThingsBoard queue service:

nano docker-compose.yml

Add the following line to the yml file. Don’t forget to replace “PUT_YOUR_LICENSE_SECRET_HERE” with your license secret obtained on the first step:

version: '3.0'
services:
  zookeeper:
    restart: always
    image: "zookeeper:3.5"
    ports:
      - "2181:2181"
    environment:
      ZOO_MY_ID: 1
      ZOO_SERVERS: server.1=zookeeper:2888:3888;zookeeper:2181
  kafka:
    restart: always
    image: wurstmeister/kafka
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_LISTENERS: INSIDE://:9093,OUTSIDE://:9092
      KAFKA_ADVERTISED_LISTENERS: INSIDE://:9093,OUTSIDE://kafka:9092
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INSIDE:PLAINTEXT,OUTSIDE:PLAINTEXT
      KAFKA_INTER_BROKER_LISTENER_NAME: INSIDE
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
  mytbpe:
    restart: always
    image: "thingsboard/tb-pe:3.5.1PE"
    depends_on:
      - kafka
    ports:
      - "8080:8080"
      - "1883:1883"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    environment:
      TB_QUEUE_TYPE: kafka
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      TB_KAFKA_SERVERS: kafka:9092
      TB_LICENSE_SECRET: PUT_YOUR_LICENSE_SECRET_HERE
      TB_LICENSE_INSTANCE_DATA_FILE: /data/license.data
    volumes:
      - ~/.mytbpe-data:/data
      - ~/.mytbpe-logs:/var/log/thingsboard
  postgres:
    restart: always
    image: "postgres:12"
    ports:
    - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - ~/.mytbpe-data/db:/var/lib/postgresql/data

AWS SQS Configuration

To access AWS SQS service, you first need to create an AWS account.

To work with AWS SQS service you will need to create your next credentials using this instruction:

Access key ID
Secret access key

Create docker compose file for ThingsBoard queue service:

nano docker-compose.yml

Add the following line to the yml file. Don’t forget to replace “YOUR_KEY”, “YOUR_SECRET” with your real AWS SQS IAM user credentials and “YOUR_REGION” with your real AWS SQS account region, and “PUT_YOUR_LICENSE_SECRET_HERE” with your license secret obtained on the first step:

version: '3.0'
services:
  mytbpe:
    restart: always
    image: "thingsboard/tb-pe:3.5.1PE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    environment:
      TB_QUEUE_TYPE: aws-sqs
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      TB_QUEUE_AWS_SQS_ACCESS_KEY_ID: YOUR_KEY
      TB_QUEUE_AWS_SQS_SECRET_ACCESS_KEY: YOUR_SECRET
      TB_QUEUE_AWS_SQS_REGION: YOUR_REGION
      TB_LICENSE_SECRET: PUT_YOUR_LICENSE_SECRET_HERE
      TB_LICENSE_INSTANCE_DATA_FILE: /data/license.data

      # These params affect the number of requests per second from each partitions per each queue.
      # Number of requests to particular Message Queue is calculated based on the formula:
      # ((Number of Rule Engine and Core Queues) * (Number of partitions per Queue) + (Number of transport queues)
      #  + (Number of microservices) + (Number of JS executors)) * 1000 / POLL_INTERVAL_MS
      # For example, number of requests based on default parameters is:
      # Rule Engine queues:
      # Main 10 partitions + HighPriority 10 partitions + SequentialByOriginator 10 partitions = 30
      # Core queue 10 partitions
      # Transport request Queue + response Queue = 2
      # Rule Engine Transport notifications Queue + Core Transport notifications Queue = 2
      # Total = 44
      # Number of requests per second = 44 * 1000 / 25 = 1760 requests
      # 
      # Based on the use case, you can compromise latency and decrease number of partitions/requests to the queue, if the message load is low.
      # By UI set the parameters - interval (1000) and partitions (1) for Rule Engine queues.
      # Sample parameters to fit into 10 requests per second on a "monolith" deployment: 
      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
    volumes:
      - ~/.mytbpe-data:/data
      - ~/.mytbpe-logs:/var/log/thingsboard
  postgres:
    restart: always
    image: "postgres:12"
    ports:
    - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - ~/.mytbpe-data/db:/var/lib/postgresql/data

You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation.

Google Pub/Sub Configuration

To access Pub/Sub service, you first need to create an Google cloud account.

To work with Pub/Sub service you will need to create a project using this instruction.

Create service account credentials with the role “Editor” or “Admin” using this instruction, and save json file with your service account credentials step 9 here.

Create docker compose file for ThingsBoard queue service:

nano docker-compose.yml

Add the following line to the yml file. Don’t forget to replace “YOUR_PROJECT_ID”, “YOUR_SERVICE_ACCOUNT” with your real Pub/Sub project id, and service account (it is whole data from json file), and “PUT_YOUR_LICENSE_SECRET_HERE” with your **license secret obtained on the first step:

version: '3.0'
services:
  mytbpe:
    restart: always
    image: "thingsboard/tb-pe:3.5.1PE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    environment:
      TB_QUEUE_TYPE: pubsub
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      TB_QUEUE_PUBSUB_PROJECT_ID: YOUR_PROJECT_ID
      TB_QUEUE_PUBSUB_SERVICE_ACCOUNT: YOUR_SERVICE_ACCOUNT
      TB_LICENSE_SECRET: PUT_YOUR_LICENSE_SECRET_HERE
      TB_LICENSE_INSTANCE_DATA_FILE: /data/license.data

      # These params affect the number of requests per second from each partitions per each queue.
      # Number of requests to particular Message Queue is calculated based on the formula:
      # ((Number of Rule Engine and Core Queues) * (Number of partitions per Queue) + (Number of transport queues)
      #  + (Number of microservices) + (Number of JS executors)) * 1000 / POLL_INTERVAL_MS
      # For example, number of requests based on default parameters is:
      # Rule Engine queues:
      # Main 10 partitions + HighPriority 10 partitions + SequentialByOriginator 10 partitions = 30
      # Core queue 10 partitions
      # Transport request Queue + response Queue = 2
      # Rule Engine Transport notifications Queue + Core Transport notifications Queue = 2
      # Total = 44
      # Number of requests per second = 44 * 1000 / 25 = 1760 requests
      # 
      # Based on the use case, you can compromise latency and decrease number of partitions/requests to the queue, if the message load is low.
      # By UI set the parameters - interval (1000) and partitions (1) for Rule Engine queues.
      # Sample parameters to fit into 10 requests per second on a "monolith" deployment: 
      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
    volumes:
      - ~/.mytbpe-data:/data
      - ~/.mytbpe-logs:/var/log/thingsboard
  postgres:
    restart: always
    image: "postgres:12"
    ports:
    - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - ~/.mytbpe-data/db:/var/lib/postgresql/data

You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation.

Azure Service Bus Configuration

To access Azure Service Bus, you first need to create an Azure account.

To work with Service Bus service you will need to create a Service Bus Namespace using this instruction.

Create Shared Access Signature using this instruction.

Create docker compose file for ThingsBoard queue service:

nano docker-compose.yml

Add the following line to the yml file. Don’t forget to replace “YOUR_NAMESPACE_NAME” with your real Service Bus namespace name, and “YOUR_SAS_KEY_NAME”, “YOUR_SAS_KEY” with your real Service Bus credentials. Note: “YOUR_SAS_KEY_NAME” it is “SAS Policy”, “YOUR_SAS_KEY” it is “SAS Policy Primary Key”, and “PUT_YOUR_LICENSE_SECRET_HERE” with your license secret obtained on the first step:

version: '3.0'
services:
  mytbpe:
    restart: always
    image: "thingsboard/tb-pe:3.5.1PE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    environment:
      TB_QUEUE_TYPE: service-bus
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      TB_QUEUE_SERVICE_BUS_NAMESPACE_NAME: YOUR_NAMESPACE_NAME
      TB_QUEUE_SERVICE_BUS_SAS_KEY_NAME: YOUR_SAS_KEY_NAME
      TB_QUEUE_SERVICE_BUS_SAS_KEY: YOUR_SAS_KEY
      TB_LICENSE_SECRET: PUT_YOUR_LICENSE_SECRET_HERE
      TB_LICENSE_INSTANCE_DATA_FILE: /data/license.data

      # These params affect the number of requests per second from each partitions per each queue.
      # Number of requests to particular Message Queue is calculated based on the formula:
      # ((Number of Rule Engine and Core Queues) * (Number of partitions per Queue) + (Number of transport queues)
      #  + (Number of microservices) + (Number of JS executors)) * 1000 / POLL_INTERVAL_MS
      # For example, number of requests based on default parameters is:
      # Rule Engine queues:
      # Main 10 partitions + HighPriority 10 partitions + SequentialByOriginator 10 partitions = 30
      # Core queue 10 partitions
      # Transport request Queue + response Queue = 2
      # Rule Engine Transport notifications Queue + Core Transport notifications Queue = 2
      # Total = 44
      # Number of requests per second = 44 * 1000 / 25 = 1760 requests
      # 
      # Based on the use case, you can compromise latency and decrease number of partitions/requests to the queue, if the message load is low.
      # By UI set the parameters - interval (1000) and partitions (1) for Rule Engine queues.
      # Sample parameters to fit into 10 requests per second on a "monolith" deployment: 
      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
    volumes:
      - ~/.mytbpe-data:/data
      - ~/.mytbpe-logs:/var/log/thingsboard
  postgres:
    restart: always
    image: "postgres:12"
    ports:
    - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - ~/.mytbpe-data/db:/var/lib/postgresql/data

You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation.

For installing RabbitMQ use this instruction.

Create docker compose file for ThingsBoard queue service:

nano docker-compose.yml

Add the following line to the yml file. Don’t forget to replace “YOUR_USERNAME” and “YOUR_PASSWORD” with your real user credentials, “localhost” and “5672” with your real RabbitMQ host and port, and “PUT_YOUR_LICENSE_SECRET_HERE” with your license secret obtained on the first step:

version: '3.0'
services:
  mytbpe:
    restart: always
    image: "thingsboard/tb-pe:3.5.1PE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    environment:
      TB_QUEUE_TYPE: rabbitmq
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      TB_QUEUE_RABBIT_MQ_USERNAME: YOUR_USERNAME
      TB_QUEUE_RABBIT_MQ_PASSWORD: YOUR_PASSWORD
      TB_QUEUE_RABBIT_MQ_HOST: localhost
      TB_QUEUE_RABBIT_MQ_PORT: 5672
      TB_LICENSE_SECRET: PUT_YOUR_LICENSE_SECRET_HERE
      TB_LICENSE_INSTANCE_DATA_FILE: /data/license.data
    volumes:
      - ~/.mytbpe-data:/data
      - ~/.mytbpe-logs:/var/log/thingsboard
  postgres:
    restart: always
    image: "postgres:12"
    ports:
    - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - ~/.mytbpe-data/db:/var/lib/postgresql/data

Confluent Cloud Configuration

To access Confluent Cloud you should first create an account, then create a Kafka cluster and get your API Key.

Create docker compose file for ThingsBoard queue service:

nano docker-compose.yml

Add the following line to the yml file. Don’t forget to replace “CLUSTER_API_KEY”, “CLUSTER_API_SECRET” and “confluent.cloud:9092” with your real Confluent Cloud bootstrap servers:

version: '3.0'
services:
  mytbpe:
    restart: always
    image: "thingsboard/tb-pe:3.5.1PE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    environment:
      TB_QUEUE_TYPE=kafka
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
    
      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

      # These params affect the number of requests per second from each partitions per each queue.
      # Number of requests to particular Message Queue is calculated based on the formula:
      # ((Number of Rule Engine and Core Queues) * (Number of partitions per Queue) + (Number of transport queues)
      #  + (Number of microservices) + (Number of JS executors)) * 1000 / POLL_INTERVAL_MS
      # For example, number of requests based on default parameters is:
      # Rule Engine queues:
      # Main 10 partitions + HighPriority 10 partitions + SequentialByOriginator 10 partitions = 30
      # Core queue 10 partitions
      # Transport request Queue + response Queue = 2
      # Rule Engine Transport notifications Queue + Core Transport notifications Queue = 2
      # Total = 44
      # Number of requests per second = 44 * 1000 / 25 = 1760 requests
      # 
      # Based on the use case, you can compromise latency and decrease number of partitions/requests to the queue, if the message load is low.
      # By UI set the parameters - interval (1000) and partitions (1) for Rule Engine queues.
      # Sample parameters to fit into 10 requests per second on a "monolith" deployment: 
      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
    volumes:
      - ~/.mytbpe-data:/data
      - ~/.mytbpe-logs:/var/log/thingsboard
  postgres:
    restart: always
    image: "postgres:12"
    ports:
    - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - ~/.mytbpe-data/db:/var/lib/postgresql/data

You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation.

Where:

PUT_YOUR_LICENSE_SECRET_HERE - placeholder for your license secret obtained on the third step;
8080:8080 - connect local port 8080 to exposed internal HTTP port 8080;
1883:1883 - connect local port 1883 to exposed internal MQTT port 1883;
7070:7070 - connect local port 7070 to exposed internal Edge RPC port 7070;
5683-5688:5683-5688/udp - connect local UDP ports 5683-5688 to exposed internal COAP and LwM2M ports;
~/.mytbpe-data:/data - mounts the host’s dir ~/.mytbpe-data to ThingsBoard data directory;
~/.mytbpe-data/db:/var/lib/postgresql/data - mounts the host’s dir ~/.mytbpe-data/db to Postgres data directory;
~/.mytbpe-logs:/var/log/thingsboard - mounts the host’s dir ~/.mytbpe-logs to ThingsBoard logs directory;
mytbpe - friendly local name of this machine;
restart: always - automatically start ThingsBoard in case of system reboot and restart in case of failure.;
thingsboard/tb-pe:3.5.1PE - docker image.

Step 4. Running

Before starting your Docker containers, execute the following commands to create directories for data storage and logs. These commands will also change the ownership of the newly created directories to the Docker container user.

The chown command is used to change the owner of the directories, and it requires sudo permissions. You may be prompted to enter a password to grant sudo access:

mkdir -p ~/.mytbpe-data && sudo chown -R 799:799 ~/.mytbpe-data
mkdir -p ~/.mytbpe-logs && sudo chown -R 799:799 ~/.mytbpe-logs

NOTE: replace directory ~/.mytbpe-data and ~/.mytbpe-logs with directories you’re planning to used in docker-compose.yml.

Set the terminal in the directory which contains the docker-compose.yml file and execute the following commands to up this docker compose directly:

docker compose up -d
docker compose logs -f mytbpe

After executing this command you can open http://{your-host-ip}:8080 in your browser (for ex. http://localhost:8080). You should see 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 always change passwords for each account in account profile page.

Detaching, stop and start commands

You can detach from session terminal using Ctrl-p Ctrl-q key sequence - the container will keep running in the background.

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

docker compose logs -f mytbpe

To stop the container:

docker compose stop mytbpe

To start the container:

docker compose start mytbpe

Troubleshooting

DNS issues

NOTE If you observe errors related to DNS issues, for example

127.0.1.1:53: cannot unmarshal DNS message

You may configure your system to use Google public DNS servers. See corresponding Linux and Mac OS instructions.

Upgrading from old PostgreSQL 9.6 to PostgreSQL 11 and ThingsBoard 3.0.1PE

In this example we’ll show steps to upgrade ThingsBoard from 2.4.3PE to 3.0.1PE.

Make a backup of your data:

sudo cp -r ~/.mytbpe-data ./.mytbpe-data-2-4-3-backup

Stop currently running docker container:

docker stop [container_id]

Upgrade old postgres to the new one:

docker run --rm -v ~/.mytbpe-data/db/:/var/lib/postgresql/9.6/data -v ~/.mytbpe-data-temp/db/:/var/lib/postgresql/11/data --env LANG=C.UTF-8 tianon/postgres-upgrade:9.6-to-11
sudo rm -rf ~/.mytbpe-data/db
sudo mv ~/.mytbpe-data-temp/db ~/.mytbpe-data/db

Start the new version of TB with following command:

docker run -it -v ~/.mytbpe-data:/data --rm thingsboard/tb-pe:3.0.1PE bash

Then please follow these steps:

apt update
apt install sudo
chown -R postgres. /data/db/
chmod 750 -R /data/db/
sudo -i -u postgres
cd /usr/lib/postgresql/11/
./bin/pg_ctl -D /data/db start
logout
/usr/share/thingsboard/bin/install/upgrade.sh --fromVersion=2.4.1
exit

After this create your docker-compose.yml and insert (we used in-memory queue as an example):

version: '3.0'
services:
  mytbpe:
    restart: always
    image: "thingsboard/tb-pe:3.0.1PE"
    ports:
      - "8080:9090"
      - "1883:1883"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    environment:
      TB_QUEUE_TYPE: in-memory
      TB_LICENSE_SECRET: YOUR_SECRET_KEY
      TB_LICENSE_INSTANCE_DATA_FILE: /data/license.data
      INTEGRATIONS_RPC_PORT: 50052
      PGDATA: /data/db
    volumes:
      - ~/.mytbpe-data:/data
      - ~/.mytbpe-logs:/var/log/thingsboard

Start ThingsBoard:

docker compose up

Upgrading from 3.0.1PE to 3.1.0PE

After 3.0.1PE PostgreSQL service was separated from ThingsBoard image and upgrading to 3.1.0PE version is not trivial.

First of all you need to create a dump of your database:

docker compose exec mytbpe sh -c "pg_dump -U postgres thingsboard > /data/thingsboard_dump"

Note You have to use your valid username for connecting to PostgreSQL

Then you need to stop service, create a new directory for the database and set permissions:

sudo cp -r ~/.mytbpe-data ./.mytbpe-data-backup
docker compose down
sudo rm -rf ~/.mytbpe-data/db
sudo chown -R 799:799 ~/.mytbpe-data
sudo chown -R 799:799 ~/.mytbpe-logs

After this you need to update docker-compose.yml as in Step 4 but with 3.1.0PE instead of 3.5.1PE:

Start PostgreSQL:

docker compose up postgres

Restore backup:

sudo cp ~/.mytbpe-data/thingsboard_dump ~/.mytbpe-data/db/thingsboard_dump
docker compose exec postgres sh -c "psql -U postgres thingsboard < /var/lib/postgresql/data/thingsboard_dump"

Upgrade ThingsBoard:

docker compose run mytbpe upgrade-tb.sh

Start ThingsBoard:

docker compose up mytbpe

Upgrade starting from 3.1.0PE

Please refer to the troubleshooting section in case you are upgrading from 3.0.0 or 3.0.1.

Below is example on how to upgrade from 3.1.0 to 3.1.1

Stop mytbpe container

docker compose stop mytbpe

Create a dump of your database:

docker compose exec postgres sh -c "pg_dump -U postgres thingsboard > /var/lib/postgresql/data/thingsboard_dump"

After this you need to update docker-compose.yml as in Step 4 but with 3.1.1PE instead of 3.2.2PE:
Change upgradeversion variable to your current ThingsBoard version.

sudo sh -c "echo '3.1.0' > ~/.mytbpe-data/.upgradeversion"

Then execute the following commands:

docker compose run mytbpe upgrade-tb.sh

Start ThingsBoard:

docker compose up -d

To upgrade ThingsBoard to the latest version those steps should be done for each intermediate version.

Please note that upgrades are not cumulative. Refer to upgrade instruction to know the right order of upgrades (e.g. if you are upgrading from 3.1.0 to 3.2.1, you need to do that in the following order: 3.1.0 -> 3.1.1 -> 3.2.0 -> 3.2.1, e.g. current version -> next release version -> etc)

In case you need to restore from the backup:

Stop mytbpe container

docker compose stop mytbpe

Update docker-compose.yml to the initial version.
Execute

docker compose exec postgres sh -c "psql -U postgres -c 'drop database thingsboard'"
docker compose exec postgres sh -c "psql -U postgres -c 'create database thingsboard'"
docker compose exec postgres sh -c "psql -U postgres thingsboard < /var/lib/postgresql/data/thingsboard_dump"

Start ThingsBoard:

docker compose up -d

If you need to copy backup to local directory in case restoring it on another server:

docker cp tb-docker_postgres_1:/var/lib/postgresql/data/thingsboard_dump .

Note: You should paste the name for your postgres container.

Next steps

Getting started guides - These guides provide quick overview of main ThingsBoard features. Designed to be completed in 15-30 minutes.
Connect your device - Learn how to connect devices based on your connectivity technology or solution.
Data visualization - These guides contain instructions how to configure complex ThingsBoard dashboards.
Data processing & actions - Learn how to use ThingsBoard Rule Engine.
IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.
Hardware samples - Learn how to connect various hardware platforms to ThingsBoard.
Advanced features - Learn about advanced ThingsBoard features.
Contribution and Development - Learn about contribution and development in ThingsBoard.

On this page

Installing ThingsBoard PE using Docker (Linux or Mac OS)

Prerequisites

Step 1. Pull ThingsBoard PE Image

Step 2. Obtain the license key

Step 3. Choose ThingsBoard queue service

AWS SQS Configuration

Google Pub/Sub Configuration

Azure Service Bus Configuration

Confluent Cloud Configuration

Step 4. Running

Detaching, stop and start commands

Troubleshooting

DNS issues

Upgrading from old PostgreSQL 9.6 to PostgreSQL 11 and ThingsBoard 3.0.1PE

Upgrading from 3.0.1PE to 3.1.0PE

Upgrade starting from 3.1.0PE

Next steps