Stand with Ukraine flag
Try it now Pricing
Edge
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
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)

doc warn icon

Rules of Compatibility Between ThingsBoard Edge and ThingsBoard Server Versions:

  • A ThingsBoard Edge version X.Y.Z is compatible with the same ThingsBoard Server version X.Y.Z and any later versions.
  • A ThingsBoard Edge version X.Y.Z is NOT compatible with ThingsBoard Server versions preceding X.Y.Z.

Example: ThingsBoard Edge version 3.3.4.1 is compatible with ThingsBoard Server version 3.3.4.1 and subsequent versions (3.4.0, 3.4.1, …). However, ThingsBoard Edge version 3.4.0 is NOT compatible with ThingsBoard Server version 3.3.4.1 or any prior versions (3.3.4, 3.3.3, …). In such scenarios, ThingsBoard Server 3.3.4.1 or a preceding version must first be upgraded to ThingsBoard Server 3.4.0 or a later version.

Please ensure that the ThingsBoard Server is updated to the latest version before proceeding.

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

Prerequisites

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

Live Demo
Local Server

Sign up for a Live Demo 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 Live Demo tenant credentials.

You can install the ThingsBoard Community 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 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 the most of 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 and populate it with configuration lines:

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

cat > docker-compose.yml <<EOF && docker compose -f docker-compose.yml up -d
version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge:3.9.0EDGE"
    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 or demo.thingsboard.io
    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
EOF

Where:

  • restart: always - automatically start ThingsBoard Edge in case of system reboot and restart in case of failure;
  • 8080:8080 - connect local port 8080 to exposed internal HTTP port 8080;
  • 1883:1883 - connect local port 1883 to exposed internal MQTT port 1883;

  • 5683-5688:5683-5688/udp - connect local UDP ports 5683-5688 to exposed internal COAP and LwM2M ports;

  • thingsboard/tb-edge:3.9.0EDGE - docker image;

  • CLOUD_ROUTING_KEY - your edge key;
  • CLOUD_ROUTING_SECRET - your edge secret;
  • CLOUD_RPC_HOST - ip address of the machine with 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 demo.thingsboard.io if you are connecting edge to ThingsBoard Live Demo for evaluation.

  • Use X.X.X.X IP address in case edge is connecting to the cloud instance in the same network or in the docker.

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.

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 and populate it with configuration lines:

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

cat > docker-compose.yml <<EOF && docker compose -f docker-compose.yml up -d
version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge:3.9.0EDGE"
    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 or demo.thingsboard.io
      TB_QUEUE_TYPE: "kafka"
      TB_KAFKA_SERVERS: "kafka:9092"
    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
  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
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
EOF

Where:

  • restart: always - automatically start ThingsBoard Edge in case of system reboot and restart in case of failure;
  • 8080:8080 - connect local port 8080 to exposed internal HTTP port 8080;
  • 1883:1883 - connect local port 1883 to exposed internal MQTT port 1883;

  • 5683-5688:5683-5688/udp - connect local UDP ports 5683-5688 to exposed internal COAP and LwM2M ports;

  • thingsboard/tb-edge:3.9.0EDGE - docker image;

  • CLOUD_ROUTING_KEY - your edge key;
  • CLOUD_ROUTING_SECRET - your edge secret;
  • CLOUD_RPC_HOST - ip address of the machine with 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 demo.thingsboard.io if you are connecting edge to ThingsBoard Live Demo for evaluation.

  • Use X.X.X.X IP address in case edge is connecting to the cloud instance in the same network or in the docker.

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.

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 and populate it with configuration lines:

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
79
80
81
82

cat > docker-compose.yml <<EOF && docker compose -f docker-compose.yml up -d
version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge:3.9.0EDGE"
    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 or demo.thingsboard.io
      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
  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: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
  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
    networks:
      - cassandra-network
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
networks:
  cassandra-network:
    driver: bridge
EOF

Where:

  • restart: always - automatically start ThingsBoard Edge in case of system reboot and restart in case of failure;
  • 8080:8080 - connect local port 8080 to exposed internal HTTP port 8080;
  • 1883:1883 - connect local port 1883 to exposed internal MQTT port 1883;

  • 5683-5688:5683-5688/udp - connect local UDP ports 5683-5688 to exposed internal COAP and LwM2M ports;

  • thingsboard/tb-edge:3.9.0EDGE - docker image;

  • CLOUD_ROUTING_KEY - your edge key;
  • CLOUD_ROUTING_SECRET - your edge secret;
  • CLOUD_RPC_HOST - ip address of the machine with 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 demo.thingsboard.io if you are connecting edge to ThingsBoard Live Demo for evaluation.

  • Use X.X.X.X IP address in case edge is connecting to the cloud instance in the same network or in the docker.

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.

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 Live Demo to log in to the ThingsBoard Edge.

Step 4. 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 Edge container logs execute the following command:

1

docker compose logs -f mytbedge

To stop the container:

1

docker compose stop mytbedge

To start the container:

1

docker compose start mytbedge

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: