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

Installing ThingsBoard Edge using Docker (Linux or Mac OS)

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.

doc warn icon

Version Compatibility Rules:

  • ThingsBoard Edge version X.Y.Z works with the ThingsBoard Server version X.Y.Z and the next two versions.

ThingsBoard Edge 3.8.0 works with ThingsBoard Server 3.8.0 and two later versions (3.9.0 and 3.9.1). You can view the ThingsBoard Server Release Notes here.

  • ThingsBoard Edge version X.Y.Z does not work with older ThingsBoard Server versions.

ThingsBoard Edge 3.9.1 does not support ThingsBoard Server 3.8.0 or any earlier versions. In such cases, the ThingsBoard Server must be upgraded to the latest version first.

Doc info icon

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 Professional Edition Edge, you will need an active ThingsBoard Professional Edition account that supports Edge functionality.

Sign up for a ThingsBoard Cloud account, which is the easiest way to get started. Throughout the rest of this tutorial, this URL will be referred to as SERVER_URL

Log in using your ThingsBoard Cloud tenant credentials.

You can install the ThingsBoard Professional Edition 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 PE 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”. If needed, update the cloud endpoint.

    • If the Edge runs in a Docker container, do not use “localhost” as the endpoint. Instead, use the IP address of the machine where ThingsBoard PE is hosted and accessible by the Edge container. For example, http://10.7.2.143:8080.
    • If you are using the ThingsBoard Cloud, there’s no need to change this setting — keep it as is.
    • 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.

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.

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:

For ThingsBoard Edge service, create a 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
version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge-pe:4.0.1EDGEPE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
      EDGE_LICENSE_INSTANCE_DATA_FILE: /data/instance-edge-license.data
      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 or thingsboard.cloud
      CLOUD_RPC_SSL_ENABLED: 'false' # set it to 'true' if you are connecting edge to thingsboard.cloud 
    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-pe:4.0.1EDGEPE: The ThingsBoard Edge PE 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.

  • CLOUD_RPC_SSL_ENABLED: Defines whether SSL is used for the connection between Edge and the ThingsBoard server. Use true to enable SSL, or false to disable it.
Doc info icon

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

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

  • Use thingsboard.cloud if you are connecting Edge to the ThingsBoard Cloud.

NOTE: thingsboard.cloud uses SSL protocol for edge communication. Please change CLOUD_RPC_SSL_ENABLED to true as well.

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

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

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 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
version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge-pe:4.0.1EDGEPE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
      EDGE_LICENSE_INSTANCE_DATA_FILE: /data/instance-edge-license.data
      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. host.docker.internal, 192.168.1.1 or thingsboard.cloud, etc.
      CLOUD_RPC_SSL_ENABLED: 'false' # set it to 'true' if you are connecting edge to thingsboard.cloud
      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: bitnami/kafka:3.8.1
    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-pe:4.0.1EDGEPE: The ThingsBoard Edge PE 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.

  • CLOUD_RPC_SSL_ENABLED: Defines whether SSL is used for the connection between Edge and the ThingsBoard server. Use true to enable SSL, or false to disable it.
Doc info icon

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

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

  • Use thingsboard.cloud if you are connecting Edge to the ThingsBoard Cloud.

NOTE: thingsboard.cloud uses SSL protocol for edge communication. Please change CLOUD_RPC_SSL_ENABLED to true as well.

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

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

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
77
78
version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge-pe:4.0.1EDGEPE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
      EDGE_LICENSE_INSTANCE_DATA_FILE: /data/instance-edge-license.data
      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 or thingsboard.cloud
      CLOUD_RPC_SSL_ENABLED: 'false' # set it to 'true' if you are connecting edge to thingsboard.cloud
      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: bitnami/kafka:3.8.1
    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-pe:4.0.1EDGEPE: The ThingsBoard Edge PE 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.

  • CLOUD_RPC_SSL_ENABLED: Defines whether SSL is used for the connection between Edge and the ThingsBoard server. Use true to enable SSL, or false to disable it.
Doc info icon

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

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

  • Use thingsboard.cloud if you are connecting Edge to the ThingsBoard Cloud.

NOTE: thingsboard.cloud uses SSL protocol for edge communication. Please change CLOUD_RPC_SSL_ENABLED to true as well.

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

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

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 local Server instance or ThingsBoard Cloud 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: