Stand with Ukraine flag
Pricing Try it now
Edge
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker PE MQTT Broker
Installation > On-premises > Docker (Linux or Mac OS)
Getting Started Documentation
Architecture API FAQ
On this page

Installing ThingsBoard Edge using Docker (Linux or Mac OS)

doc warn icon

Version Compatibility Rules - Read before proceeding

Before installing ThingsBoard Edge, ensure that ThingsBoard Server is installed and updated to the latest version.

Additionally, verify that the ThingsBoard Edge and ThingsBoard Server versions are compatible.

Compatibility rules:

  • ThingsBoard Edge version X.Y.Z works with ThingsBoard Server version X.Y.Z and the next two versions.
  • ThingsBoard Edge version X.Y.Z does not work with older ThingsBoard Server versions.
    • Example: ThingsBoard Edge 3.9.1 does not support ThingsBoard Server 3.8.0 or earlier versions. The ThingsBoard Server must be upgraded to the latest version first.

Note: If you run an older version of ThingsBoard Edge (e.g., version 3.6.0), the ThingsBoard team cannot guarantee the availability or proper functioning of all features.

This guide provides step-by-step instructions for running ThingsBoard Edge on Linux or Mac OS using Docker.

Prerequisites

To start running ThingsBoard Community Edition Edge, you will need an active ThingsBoard Community Edition account that supports Edge functionality.

You can install the ThingsBoard CE local server. For this, please refer to the ThingsBoard installation guide.

The local server can be accessed via http://localhost:8080. Throughout this tutorial, we will refer to this URL as SERVER_URL. Log in with:

Edge Hardware Requirements

The hardware requirements for ThingsBoard Edge are determined by the number of connected devices and the intensity of interactions with the platform interface. To ensure optimal performance, we recommend the following:

  • At least 1GB of RAM (Light workload): It is suitable for minimal interactions with the platform interface, such as dashboards and device management, and fewer than 100 connected devices.
  • At least 4GB of RAM (Heavy workload): This configuration is suitable for intense platform interactions and 100+ devices connected to a single machine.

Deploying a New Edge Instance

To create a new Edge:

  • Sign in to your ThingsBoard CE instance and navigate to the Edge Management > Instances section. Click the ”+” icon in the top right corner and select the “Add new edge” option.

  • Enter a name for the Edge you are creating. For example, “My New Edge”. Click the “Add” button to confirm the addition of the Edge instance.

  • Your new Edge is created and will appear at the top of the list, as entries are sorted by creation time by default.

Sign in to your ThingsBoard CE instance and navigate to the Edge Management > Instances section. Click the "+" icon in the top right corner and select the "Add new edge" option.

Sign in to your ThingsBoard CE instance and navigate to the Edge Management > Instances section. Click the ”+” icon in the top right corner and select the “Add new edge” option.

Enter a name for the Edge you are creating. For example, "My New Edge". Click the "Add" button to confirm the addition of the Edge instance.

Enter a name for the Edge you are creating. For example, “My New Edge”. Click the “Add” button to confirm the addition of the Edge instance.

Your new Edge is created and will appear at the top of the list, as entries are sorted by creation time by default.

Your new Edge is created and will appear at the top of the list, as entries are sorted by creation time by default.

Docker installation

Doc info icon

ThingsBoard supports Docker Compose V2 (Docker Desktop or Compose plugin) starting from 3.4.2 release.

We strongly recommend upgrading to and using Docker Compose V2, as Docker no longer supports docker-compose as a standalone setup.

doc warn icon

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

Guided Installation Using ThingsBoard Server Pre-configured Instructions

Once the Edge instance has been created, the installation instructions will be available for use. Each Edge has preset configurations that contain important credentials, such as Edge Secret, Edge Key, etc. To access these configurations:

  • Click on the Edge entity to open its details.

  • Click the “Install & Connection Instructions” button.

  • Follow the instructions to install Edge and connect it to the server.

Click on the Edge entity to open its details.

Click on the Edge entity to open its details.

Click the "Install & Connection Instructions" button.

Click the “Install & Connection Instructions” button.

Follow the instructions to install Edge and connect it to the server.

Follow the instructions to install Edge and connect it to the server.

Manual Installation and Configuration

If for any reason you are unable to use the prepared ThingsBoard Server Instructions above, please follow the steps below. These steps will guide you through installing and configuring the Edge by yourself.

Step 1. Running ThingsBoard Edge

Here you can find ThingsBoard Edge docker image:

Click on Copy Edge Key and Copy Edge Secret in the edge details section. This will copy your edge credentials to your clipboard. Be sure to store them in a secure location, as these values will be needed in the following steps.

Step 2. Choose Queue and/or Database Services

ThingsBoard Edge is able to use different 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 most of the ThingsBoard production environments now.

  • Hybrid implementation combines PostgreSQL and Cassandra databases with Kafka queue service. It is recommended if you plan to manage 1M+ devices in production or handle high data ingestion rate (more than 5000 msg/sec).

Create a docker compose file for the ThingsBoard Edge service:

In Memory (built-in and default)
Kafka (recommended for on-prem, production installations)
Hybrid (PostgreSQL+Cassandra with Kafka queue service)

Create the docker compose file:

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

version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge:4.3.0.1EDGE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
      CLOUD_ROUTING_KEY: PUT_YOUR_EDGE_KEY_HERE # e.g. 19ea7ee8-5e6d-e642-4f32-05440a529015
      CLOUD_ROUTING_SECRET: PUT_YOUR_EDGE_SECRET_HERE # e.g. bztvkvfqsye7omv9uxlp
      CLOUD_RPC_HOST: PUT_YOUR_CLOUD_IP # e.g. 192.168.1.1
    volumes:
      - tb-edge-data:/data
      - tb-edge-logs:/var/log/tb-edge
  postgres:
    restart: always
    image: "postgres:15"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: tb-edge
      POSTGRES_PASSWORD: postgres
    volumes:
      - tb-edge-postgres-data:/var/lib/postgresql/data

volumes:
  tb-edge-data:
    name: tb-edge-data
  tb-edge-logs:
    name: tb-edge-logs
  tb-edge-postgres-data:
    name: tb-edge-postgres-data

Where:

  • restart: always: ThingsBoard Edge automatically starts on system reboot or after a failure.
  • 8080:8080: Connect local port 8080 to the container’s internal HTTP port 8080.
  • 1883:1883: Connect local port 1883 to the container’s internal MQTT port 1883.

  • 5683-5688:5683-5688/udp: Connect local UDP ports 5683–5688 to the container’s internal CoAP and LwM2M ports.

  • thingsboard/tb-edge:4.3.0.1EDGE: The ThingsBoard Edge Docker image.

  • CLOUD_ROUTING_KEY: Enter the actual Edge key.
  • CLOUD_ROUTING_SECRET: Enter the actual Edge secret.
  • CLOUD_RPC_HOST: he IP address or hostname of the machine running the ThingsBoard platform.
Doc info icon

Please set CLOUD_RPC_HOST with an IP address of the machine where ThingsBoard version is running:

  • DO NOT use ‘localhost’ - ‘localhost’ is the ip address of the edge service in the docker container.

  • Use X.X.X.X IP address if the Edge is connected to the Cloud instance in the same network or Docker environment.

Doc info icon

If ThingsBoard Edge is set to run on the same machine where the ThingsBoard server is operating, you need to update port configuration to prevent port collision between the ThingsBoard server and ThingsBoard Edge.

Ensure that the ports 18080, 11883, 15683-15688 are not used by any other application.

To update the port configuration in the docker-compose.yml file, run:

1

sed -i 's/8080:8080/18080:8080/; s/1883:1883/11883:1883/; s/5683-5688:5683-5688\/udp/15683-15688:5683-5688\/udp/' 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 mytbedge

Apache Kafka is an open source stream processing software platform.

Create the docker compose file:

1

nano docker-compose.yml

Add the following configuration 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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge:4.3.0.1EDGE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
      CLOUD_ROUTING_KEY: PUT_YOUR_EDGE_KEY_HERE # e.g. 19ea7ee8-5e6d-e642-4f32-05440a529015
      CLOUD_ROUTING_SECRET: PUT_YOUR_EDGE_SECRET_HERE # e.g. bztvkvfqsye7omv9uxlp
      CLOUD_RPC_HOST: PUT_YOUR_CLOUD_IP # e.g. 192.168.1.1
      TB_QUEUE_TYPE: "kafka"
      TB_KAFKA_SERVERS: "kafka:9092"
    volumes:
      - tb-edge-data:/data
      - tb-edge-logs:/var/log/tb-edge
    extra_hosts:
      - "host.docker.internal:host-gateway"
  postgres:
    restart: always
    image: "postgres:15"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: tb-edge
      POSTGRES_PASSWORD: postgres
    volumes:
      - tb-edge-postgres-data:/var/lib/postgresql/data
  kafka:
    restart: always
    image: bitnamilegacy/kafka:4.0
    ports:
      - 9092
      - 9093 #for Kraft
    environment:
      ALLOW_PLAINTEXT_LISTENER: "yes"
      KAFKA_CFG_LISTENERS: "INTERNAL://:9092,CONTROLLER://:9093"
      KAFKA_CFG_ADVERTISED_LISTENERS: "INTERNAL://kafka:9092"
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "INTERNAL:PLAINTEXT,CONTROLLER:PLAINTEXT"
      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "INTERNAL"
      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
volumes:
  tb-edge-data:
    name: tb-edge-data
  tb-edge-logs:
    name: tb-edge-logs
  tb-edge-postgres-data:
    name: tb-edge-postgres-data
  kafka-data:
    driver: local

Where:

  • restart: always: ThingsBoard Edge automatically starts on system reboot or after a failure.
  • 8080:8080: Connect local port 8080 to the container’s internal HTTP port 8080.
  • 1883:1883: Connect local port 1883 to the container’s internal MQTT port 1883.

  • 5683-5688:5683-5688/udp: Connect local UDP ports 5683–5688 to the container’s internal CoAP and LwM2M ports.

  • thingsboard/tb-edge:4.3.0.1EDGE: The ThingsBoard Edge Docker image.

  • CLOUD_ROUTING_KEY: Enter the actual Edge key.
  • CLOUD_ROUTING_SECRET: Enter the actual Edge secret.
  • CLOUD_RPC_HOST: he IP address or hostname of the machine running the ThingsBoard platform.
Doc info icon

Please set CLOUD_RPC_HOST with an IP address of the machine where ThingsBoard version is running:

  • DO NOT use ‘localhost’ - ‘localhost’ is the ip address of the edge service in the docker container.

  • Use X.X.X.X IP address if the Edge is connected to the Cloud instance in the same network or Docker environment.

Doc info icon

If ThingsBoard Edge is set to run on the same machine where the ThingsBoard server is operating, you need to update port configuration to prevent port collision between the ThingsBoard server and ThingsBoard Edge.

Ensure that the ports 18080, 11883, 15683-15688 are not used by any other application.

To update the port configuration in the docker-compose.yml file, run:

1

sed -i 's/8080:8080/18080:8080/; s/1883:1883/11883:1883/; s/5683-5688:5683-5688\/udp/15683-15688:5683-5688\/udp/' 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 mytbedge

Apache Cassandra is an open source NoSQL database designed to manage massive amounts of data.

Apache Kafka is an open source stream processing software platform.

Create the docker compose file:

1

nano docker-compose.yml

Add the following configuration 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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge:4.3.0.1EDGE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
      CLOUD_ROUTING_KEY: PUT_YOUR_EDGE_KEY_HERE # e.g. 19ea7ee8-5e6d-e642-4f32-05440a529015
      CLOUD_ROUTING_SECRET: PUT_YOUR_EDGE_SECRET_HERE # e.g. bztvkvfqsye7omv9uxlp
      CLOUD_RPC_HOST: PUT_YOUR_CLOUD_IP # e.g. 192.168.1.1
      TB_QUEUE_TYPE: "kafka"
      TB_KAFKA_SERVERS: "kafka:9092"
      DATABASE_TS_TYPE: "cassandra"
      CASSANDRA_URL: "cassandra:9042"
    volumes:
      - tb-edge-data:/data
      - tb-edge-logs:/var/log/tb-edge
    extra_hosts:
      - "host.docker.internal:host-gateway"
  postgres:
    restart: always
    image: "postgres:15"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: tb-edge
      POSTGRES_PASSWORD: postgres
    volumes:
      - tb-edge-postgres-data:/var/lib/postgresql/data
  kafka:
    restart: always
    image: bitnamilegacy/kafka:4.0
    ports:
      - 9092
      - 9093 #for Kraft
    environment:
      ALLOW_PLAINTEXT_LISTENER: "yes"
      KAFKA_CFG_LISTENERS: "INTERNAL://:9092,CONTROLLER://:9093"
      KAFKA_CFG_ADVERTISED_LISTENERS: "INTERNAL://kafka:9092"
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "INTERNAL:PLAINTEXT,CONTROLLER:PLAINTEXT"
      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "INTERNAL"
      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
  cassandra:
    restart: always
    image: "cassandra:4.0"
    container_name: cassandra
    environment:
      CASSANDRA_CLUSTER_NAME: "Thingsboard Edge Cluster"
      CASSANDRA_KEYSPACE_NAME: "tb_edge"
      CASSANDRA_LOCAL_DATACENTER: "datacenter1"
    ports:
      - 9042:9042
    volumes:
      - ./data/cassandra:/var/lib/cassandra
volumes:
  tb-edge-data:
    name: tb-edge-data
  tb-edge-logs:
    name: tb-edge-logs
  tb-edge-postgres-data:
    name: tb-edge-postgres-data
  kafka-data:
    driver: local

Where:

  • restart: always: ThingsBoard Edge automatically starts on system reboot or after a failure.
  • 8080:8080: Connect local port 8080 to the container’s internal HTTP port 8080.
  • 1883:1883: Connect local port 1883 to the container’s internal MQTT port 1883.

  • 5683-5688:5683-5688/udp: Connect local UDP ports 5683–5688 to the container’s internal CoAP and LwM2M ports.

  • thingsboard/tb-edge:4.3.0.1EDGE: The ThingsBoard Edge Docker image.

  • CLOUD_ROUTING_KEY: Enter the actual Edge key.
  • CLOUD_ROUTING_SECRET: Enter the actual Edge secret.
  • CLOUD_RPC_HOST: he IP address or hostname of the machine running the ThingsBoard platform.
Doc info icon

Please set CLOUD_RPC_HOST with an IP address of the machine where ThingsBoard version is running:

  • DO NOT use ‘localhost’ - ‘localhost’ is the ip address of the edge service in the docker container.

  • Use X.X.X.X IP address if the Edge is connected to the Cloud instance in the same network or Docker environment.

Doc info icon

If ThingsBoard Edge is set to run on the same machine where the ThingsBoard server is operating, you need to update port configuration to prevent port collision between the ThingsBoard server and ThingsBoard Edge.

Ensure that the ports 18080, 11883, 15683-15688 are not used by any other application.

To update the port configuration in the docker-compose.yml file, run:

1

sed -i 's/8080:8080/18080:8080/; s/1883:1883/11883:1883/; s/5683-5688:5683-5688\/udp/15683-15688:5683-5688\/udp/' 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 mytbedge

Step 3. Open ThingsBoard Edge UI

Once the Edge service is started, open the Edge UI at http://localhost:8080.

Doc info icon

If the Edge HTTP bind port was changed to 18080 during Edge installation, access the ThingsBoard Edge instance at http://localhost:18080.

Please use your tenant credentials from ThingsBoard Server to log in to the ThingsBoard Edge.

Step 4. Detaching, Stop and Start Commands

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

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

1

docker compose logs -f mytbedge

To stop the container, run:

1

docker compose stop mytbedge

To start the container, run:

1

docker compose start mytbedge

To stop and clean up the docker compose environment, and delete all related data, run:

1

docker compose down -v

To recreate the containers, volumes, and network, run:

1

docker compose up -d

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

Congratulations! You have successfully provisioned, installed and connected ThingsBoard Edge to ThingsBoard server.

You can continue with Getting started guide to get the basic knowledge of ThingsBoard Edge or you can jump directly to more advanced topics: