Installing ThingsBoard Edge using Docker (Windows)

• Prerequisites
  • Edge Hardware Requirements
  • Provisioning a new Edge instance on the ThingsBoard server
  • Docker installation
• Installation and Configuration
  • Step 1. Running ThingsBoard Edge
  • Step 2. Open ThingsBoard Edge UI
  • Step 3. Detaching, stop and start commands
• Troubleshooting
  • DNS issues
• Next Steps

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

Prerequisites

To start utilizing the ThingsBoard Edge, it is essential to have an operational ThingsBoard server that supports Edge functionality.

The easiest way is to use ThingsBoard Cloud server.

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

Edge Hardware Requirements

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

• Light Usage: If you intend to operate ThingsBoard Edge with minimal GUI interactions (such as local dashboards and device management) and anticipate connecting fewer than 100 devices to a single machine, a minimum of 1GB of RAM should suffice.

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

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

• Enter a name for your edge. For instance, “My New Edge”. If necessary, update the cloud endpoint. This URL should be accessible from the edge. If the edge is running in a Docker container, using “localhost” is incorrect. It must be the IP address of the machine where ThingsBoard PE is running and accessible by the edge container. If you are using the ThingsBoard Cloud server to evaluate the edge, leave this setting as it is. Click “Add” to confirm adding your new Edge.

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

Docker installation

• Install Docker Toolbox for Windows

Installation and Configuration

Step 1. Running ThingsBoard Edge

Here you can find ThingsBoard Edge docker image:

• thingsboard/tb-edge-pe

Windows users should use docker managed volume for ThingsBoard Edge DataBase. Create docker volume (for ex. mytb-edge-data) before executing docker run command: Open “Docker Quickstart Terminal”. Execute the following command to create docker volume:

1
2
3
docker volume create mytb-edge-data
docker volume create mytb-edge-logs
docker volume create mytb-edge-data-db

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.

Create docker compose file for ThingsBoard Edge service:

1
docker-compose.yml

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
version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge-pe:3.8.0EDGEPE"
    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:
      - mytb-edge-data:/data
      - mytb-edge-logs:/var/log/tb-edge
  postgres:
    restart: always
    image: "postgres:15"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: tb-edge
      POSTGRES_PASSWORD: postgres
    volumes:
      - mytb-edge-data-db:/var/lib/postgresql/data
volumes:
  mytb-edge-data:
    external: true
  mytb-edge-logs:
    external: true
  mytb-edge-data-db:
    external: true

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-pe:3.8.0EDGEPE - 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;

• CLOUD_RPC_SSL_ENABLED - enable or disable SSL connection to server from edge.

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 in case you are connecting edge to 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 in case edge is connecting to the cloud instance in the same network or in the docker.

If ThingsBoard Edge is set to run on the same machine where the ThingsBoard PE 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

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 2. Open ThingsBoard Edge UI

Once started, you will be able to open ThingsBoard Edge UI using the following link http://localhost:8080.

If you changed the Edge HTTP bind port to 18080 during Edge installation, use the following ThingsBoard Edge UI link: http://localhost:18080.

Please use your tenant credentials from local Server instance or ThingsBoard Cloud to log in to the ThingsBoard Edge.

Step 3. 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

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

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:

• Getting started guide - Provide quick overview of main ThingsBoard Edge features. Designed to be completed in 15-30 minutes:

• Edge Rule Engine:

  • Rule Chain Templates - Learn how to use ThingsBoard Edge Rule Chain Templates.

  • Provision Rule Chains from cloud to edge - Learn how to provision edge rule chains from cloud to edge.

• Security:
  • gRPC over SSL/TLS - Learn how to configure gRPC over SSL/TLS for communication between edge and cloud.

• Features:

  • Edge Status - Learn about Edge Status page on ThingsBoard Edge.

  • Cloud Events - Learn about Cloud Events page on ThingsBoard Edge.

• Use cases:

  • Manage alarms and RPC requests on edge devices - This guide will show how to generate local alarms on the edge and send RPC requests to devices connected to edge:

  • Data filtering and traffic reduce - This guide will show how to send to cloud from edge only filterd amount of device data:

• Roadmap - ThingsBoard Edge roadmap.