Stand with Ukraine flag
Try it now Pricing
Community Edition
Installation > On premise > Docker (Linux or Mac OS)
Getting Started Documentation Devices Library Guides
Architecture API FAQ
On this page

Installing ThingsBoard using Docker (Linux or Mac OS)

Doc info icon
ThingsBoard Cloud

We recommend to use ThingsBoard Cloud - fully managed, scalable and fault-tolerant platform for your IoT applications
ThingsBoard Cloud is for everyone who would like to use ThingsBoard but don’t want to host their own instance of the platform.

This guide will help you to install and start ThingsBoard using Docker on Linux or Mac OS.

Prerequisites

Install Docker:

doc warn icon

Don’t forget to add your linux user to the docker group. See Manage Docker as a non-root user.

Running

In this instruction thingsboard/tb-postgres image will be used. It contains a single instance of ThingsBoard with PostgreSQL database.

Running this image requires a server with at least 4GB of RAM (8GB is recommended) and minimum load (few messages per second).

Choose ThingsBoard queue service

ThingsBoard platform currently supports two type of messaging brokers for storing the messages and communication between ThingsBoard services: In-memory and Kafka-based brokers.

  • 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.

  • 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.

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

Create docker compose file for ThingsBoard queue service:

1
nano docker-compose.yml

Add the following lines to the yml file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
version: '3.0'
services:
  mytb:
    restart: always
    image: "thingsboard/tb-postgres"
    ports:
      - "8080:9090"
      - "1883:1883"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    environment:
      TB_QUEUE_TYPE: in-memory
    volumes:
      - ~/.mytb-data:/data
      - ~/.mytb-logs:/var/log/thingsboard

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

Create docker compose file for ThingsBoard queue service:

1
nano docker-compose.yml

Add the following lines to the yml file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
version: '3.2'
services:
  kafka:
    restart: always
    image: bitnami/kafka:3.8.1
    ports:
      - 9092:9092 #to localhost:9092 from host machine
      - 9093 #for Kraft
      - 9094 #to kafka:9094 from within Docker network
    environment:
      ALLOW_PLAINTEXT_LISTENER: "yes"
      KAFKA_CFG_LISTENERS: "OUTSIDE://:9092,CONTROLLER://:9093,INSIDE://:9094"
      KAFKA_CFG_ADVERTISED_LISTENERS: "OUTSIDE://localhost:9092,INSIDE://kafka:9094"
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "INSIDE:PLAINTEXT,OUTSIDE:PLAINTEXT,CONTROLLER:PLAINTEXT"
      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "INSIDE"
      KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE: "false"
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
      KAFKA_CFG_PROCESS_ROLES: "controller,broker" #KRaft
      KAFKA_CFG_NODE_ID: "0" #KRaft
      KAFKA_CFG_CONTROLLER_LISTENER_NAMES: "CONTROLLER" #KRaft
      KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: "0@kafka:9093" #KRaft
    volumes:
      - kafka-data:/bitnami
  mytb:
    restart: always
    image: "thingsboard/tb-postgres"
    depends_on:
      - kafka
    ports:
      - "8080:9090"
      - "1883:1883"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    environment:
      TB_QUEUE_TYPE: kafka
      TB_KAFKA_SERVERS: kafka:9094
    volumes:
      - ~/.mytb-data:/data
      - ~/.mytb-logs:/var/log/thingsboard
volumes:
  kafka-data:
    driver: local

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:

1
nano docker-compose.yml

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
version: '3.0'
services:
  mytb:
    restart: always
    image: "thingsboard/tb-postgres"
    ports:
      - "8080:9090"
      - "1883:1883"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    environment:
      TB_QUEUE_TYPE: kafka
      TB_KAFKA_SERVERS: localhost:9092
      TB_QUEUE_KAFKA_REPLICATION_FACTOR: 3
      TB_QUEUE_KAFKA_USE_CONFLUENT_CLOUD: true
      TB_QUEUE_KAFKA_CONFLUENT_SASL_JAAS_CONFIG: 'org.apache.kafka.common.security.plain.PlainLoginModule required username="CLUSTER_API_KEY" password="CLUSTER_API_SECRET";'

      # 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:
      - ~/.mytb-data:/data
      - ~/.mytb-logs:/var/log/thingsboard

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

Where:

  • 8080:9090 - connect local port 8080 to exposed internal HTTP port 9090
  • 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
  • ~/.mytb-data:/data - mounts the host’s dir ~/.mytb-data to ThingsBoard DataBase data directory
  • ~/.mytb-logs:/var/log/thingsboard - mounts the host’s dir ~/.mytb-logs to ThingsBoard logs directory
  • mytb - friendly local name of this machine
  • restart: always - automatically start ThingsBoard in case of system reboot and restart in case of failure.
  • image: thingsboard/tb-postgres - docker image, can be also thingsboard/tb-cassandra or thingsboard/tb

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:

doc warn icon

For Docker Desktop users on MacOS, that utilize Synchronized file shares feature (enabled by default for /Users subdirectories):

Please note that you need to omit changing host volume ownership, since it is resolved automatically by virtualization engine.

mkdir -p ~/.mytb-data

mkdir -p ~/.mytb-logs

1
2
mkdir -p ~/.mytb-data && sudo chown -R 799:799 ~/.mytb-data
mkdir -p ~/.mytb-logs && sudo chown -R 799:799 ~/.mytb-logs

NOTE: Replace directory ~/.mytb-data and ~/.mytb-logs with directories you’re planning to use 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:

1
docker compose up -d && docker compose logs -f mytb

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: sysadmin@thingsboard.org / sysadmin
  • Tenant Administrator: tenant@thingsboard.org / tenant
  • Customer User: customer@thingsboard.org / 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 container logs execute the following command:

1
docker compose logs -f mytb

To stop the container:

1
docker compose stop mytb

To start the container:

1
docker compose start mytb
Doc info icon

Docker Compose as docker-compose (with a hyphen) is deprecated. It is recommended to use Docker Compose V2 instead.
If you still rely on docker compose as standalone here is the list of the above commands:
docker-compose logs -f mytb
docker-compose stop mytb
docker-compose start mytb

Upgrading

In order to update to the latest image, execute the following commands:

1
2
3
4
5
docker pull thingsboard/tb-postgres
docker compose stop
docker run -it -v ~/.mytb-data:/data --rm thingsboard/tb-postgres upgrade-tb.sh
docker compose rm mytb
docker compose up

NOTE: if you use different database change image name in all commands from thingsboard/tb-postgres to thingsboard/tb-cassandra or thingsboard/tb correspondingly.

NOTE: replace host’s directory ~/.mytb-data with directory used during container creation.

NOTE: if you have used one database and want to try another one, then remove the current docker container using docker-compose rm command and use different directory for ~/.mytb-data in docker-compose.yml.

Doc info icon

If you still rely on Docker Compose as docker-compose (with a hyphen) here is the list of the above commands:
docker pull thingsboard/tb-postgres
docker-compose stop
docker run -it -v ~/.mytb-data:/data –rm thingsboard/tb-postgres upgrade-tb.sh
docker-compose rm mytb
docker-compose up

Troubleshooting

DNS issues

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

1
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.

Next steps