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 using the ThingsBoard Edge, it is essential to have a running ThingsBoard server that supports Edge functionality.

The easiest way is to use the Live Demo server.

Alternatively, you can install the ThingsBoard Community Edition server on-premise. For this, please refer to the ThingsBoard installation guide.

Edge Hardware Requirements

The hardware specifications required for ThingsBoard Edge are determined by both the number of locally connected devices and the level of GUI interaction:

  • Light Usage: If you intend to operate ThingsBoard Edge with minimal GUI interactions (such as local dashboards and device management) and expect to connect fewer than 100 devices to a single machine, at least 1GB of RAM should be sufficient.

  • Heavy Usage: Conversely, for heavy GUI interactions and connections to 100+ devices on a single machine, we recommend allocating at least 4GB of RAM to ensure optimal performance.

Provisioning a new Edge instance on the ThingsBoard server

Additionally, you will need to provision Edge on the ThingsBoard server.

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

  • Enter a name for your Edge. For instance, “My New Edge”. Click “Add” to confirm the addition of your new Edge.

  • Your new Edge should now appear at the top of the list, as entries are sorted by creation time by default.

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

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

Enter a name for your Edge. For instance, "My New Edge". Click "Add" to confirm the addition of your new Edge.

Enter a name for your Edge. For instance, “My New Edge”. Click “Add” to confirm the addition of your new Edge.

Your new Edge should now appear at the top of the list, as entries are sorted by creation time by default.

Your new Edge should now appear at the top of the list, as entries are sorted by creation time by default.

Docker installation

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

The easiest way to install and connect the Edge to the Server is to follow the installation instructions provided by the ThingsBoard Server. For every Edge Entity, the Server displays the instructions with pre-populated fields such as the Edge secret key, Edge routing key, Edge RPC host URI, and so on

Please follow the steps below to use these prepared instructions:

  • Click an Edge entity row to open its details;

  • Click on the “Install & Connect Instructions” button;

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

Click an Edge entity row to open its details;

Click an Edge entity row to open its details;

Click on the "Install & Connect Instructions" button;

Click on the “Install & Connect Instructions” button;

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

Follow the instructions to install Edge and connect 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 docker compose file for the ThingsBoard Edge service:

1

nano docker-compose.yml

Add the following lines to the docker-compose.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: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

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 additional configuration parameters to prevent port collision between the ThingsBoard server and ThingsBoard Edge.

Please update next lines of docker-compose.yml file:
…
ports:
- “18080:8080”
- “11883:1883”
- “15683-15688:5683-5688/udp”
…

Ensure that the ports listed above (18080, 11883, 15683-15688) are not being used by any other application.

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
2

docker compose up -d
docker compose logs -f mytbedge
Doc info icon

ThingsBoard supports Docker Compose V2 (Docker Desktop or Compose plugin) starting from 3.4.2 release, because docker-compose as standalone setup is no longer supported by Docker.

We strongly recommend to update to Docker Compose V2 and use it.

If you still rely on using Docker Compose as docker-compose (with a hyphen), then please execute the following commands to start ThingsBoard:
docker-compose up -d
docker-compose logs -f mytbedge

Apache Kafka is an open source stream processing software platform.

Create docker compose file for the ThingsBoard Edge service:

1

nano docker-compose.yml

Add the following lines to the docker-compose.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

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

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 additional configuration parameters to prevent port collision between the ThingsBoard server and ThingsBoard Edge.

Please update next lines of docker-compose.yml file:
…
ports:
- “18080:8080”
- “11883:1883”
- “15683-15688:5683-5688/udp”
…

Ensure that the ports listed above (18080, 11883, 15683-15688) are not being used by any other application.

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
2

docker compose up -d
docker compose logs -f mytbedge
Doc info icon

ThingsBoard supports Docker Compose V2 (Docker Desktop or Compose plugin) starting from 3.4.2 release, because docker-compose as standalone setup is no longer supported by Docker.

We strongly recommend to update to Docker Compose V2 and use it.

If you still rely on using Docker Compose as docker-compose (with a hyphen), then please execute the following commands to start ThingsBoard:
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 docker compose file for the ThingsBoard Edge service:

1

nano docker-compose.yml

Add the following lines to the docker-compose.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
79
80

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

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 additional configuration parameters to prevent port collision between the ThingsBoard server and ThingsBoard Edge.

Please update next lines of docker-compose.yml file:
…
ports:
- “18080:8080”
- “11883:1883”
- “15683-15688:5683-5688/udp”
…

Ensure that the ports listed above (18080, 11883, 15683-15688) are not being used by any other application.

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
2

docker compose up -d
docker compose logs -f mytbedge
Doc info icon

ThingsBoard supports Docker Compose V2 (Docker Desktop or Compose plugin) starting from 3.4.2 release, because docker-compose as standalone setup is no longer supported by Docker.

We strongly recommend to update to Docker Compose V2 and use it.

If you still rely on using Docker Compose as docker-compose (with a hyphen), then please execute the following commands to start ThingsBoard:
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 you changed the Edge HTTP bind port to 18080 during the Edge installation, use the http://localhost:18080 link to access the ThingsBoard Edge UI.

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
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 mytbedge
docker-compose stop mytbedge
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: