Installing ThingsBoard Edge using Docker (Linux or Mac OS)

Prerequisites
Step 1. Pull ThingsBoard Edge Images
Step 2. Running ThingsBoard Edge
Step 3. Open ThingsBoard Edge UI
Step 4. Detaching, stop and start commands
Troubleshooting
- DNS issues
- Database issues
Next Steps

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

Prerequisites

ThingsBoard Cloud server

To start using ThingsBoard Edge you need to have ThingsBoard PE server that supports edge functionality up and running.

The easiest way is to use ThingsBoard Cloud server.
The alternative option is to install ThingsBoard Professional Edition server that supports edge functionality on-premise. Please visit Install PE to install 3.3 version or higher of server that supports edge functionality.

Edge provision on cloud

Additionally, you will need to provision ThingsBoard Edge on cloud server. Please follow Step 1 first if you skipped it.

Once ThingsBoard Edge provisioned on cloud server please follow installation steps below.

Docker installation

Edge hardware requirements

Hardware requirements depend on an amount of devices connected to the edge and GUI usage locally.

To run ThingsBoard Edge without heavily usage of GUI (local dashboards, device management etc.) and relatively small amount of devices (under 100) on a single machine you will need at least 1GB of RAM.

To run ThingsBoard Edge with heavily usage of GUI (local dashboards, device management etc.) and with 100+ devices on a single machine we recommend having at least 4GB of RAM.

Step 1. Pull ThingsBoard Edge Images

Make sure your have logged in to docker hub using command line.

docker pull thingsboard/tb-edge-pe:3.5.1EDGEPE

Step 2. Running ThingsBoard Edge

Here you can find ThingsBoard Edge docker image:

thingsboard/tb-edge-pe

Create docker compose file for ThingsBoard Edge service:

nano docker-compose.yml

将以下行添加到yml文件：

version: '3.0'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge-pe:3.5.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.250 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:12"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: tb-edge
      POSTGRES_PASSWORD: postgres
    volumes:
      - ~/.mytb-edge-data/db:/var/lib/postgresql/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;
mytb-edge-data:/data - mounts the host’s dir mytb-edge-data to ThingsBoard Edge DataBase data directory;
mytb-edge-logs:/var/log/tb-edge - mounts the host’s dir mytb-edge-logs to ThingsBoard Edge logs directory;
mytb-edge-data/db:/var/lib/postgresql/data - mounts the host’s dir mytb-edge-data/db to Postgres data directory;
thingsboard/tb-edge-pe:3.5.1EDGEPE - 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.

在启动Docker容器之前请运行以下命令以创建用于存储数据和日志的目录然后将其所有者更改为Docker容器用户，以便能够更改用户使用chown命令该命令需要sudo权限（该命令将要求sudo访问的密码）：

mkdir -p ~/.mytb-edge-data && sudo chown -R 799:799 ~/.mytb-edge-data
mkdir -p ~/.mytb-edge-logs && sudo chown -R 799:799 ~/.mytb-edge-logs

NOTE: Replace directory ~/.mytb-edge-data and ~/.mytb-edge-logs with directories you’re planning to use in docker-compose.yml.

在包含该文件的目录终端中执行以下命令启动此docker compos：docker-compose.yml

docker compose pull
docker compose up -d
docker compose logs -f mytbedge

Step 3. Open ThingsBoard Edge UI

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

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

Step 4. Detaching, stop and start commands

你可以使用Ctrl-p Ctrl-q与会话终端分离容器将继续在后台运行。

如果出现任何问题可以检查服务日志中的错误例如：要查看ThingsBoard容器日志。
请执行以下命令：

docker compose logs -f mytbedge

停止容器：

docker compose stop mytbedge

启动容器：

docker compose start mytbedge

Troubleshooting

DNS issues

注意：如果你发现与DNS问题相关的错误，例如

127.0.1.1:53: cannot unmarshal DNS message

你可以将系统配置为使用 Google公共DNS服务器。
请参阅相应的Linux和Mac OS说明

Database issues

NOTE If you see errors related to edge is not able to connect to database, for example

Caused by: org.postgresql.util.PSQLException: Connection to localhost:5432 refused. Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections.
mytbedge_1_f5648ad89a6e | 	at org.postgresql.core.v3.ConnectionFactoryImpl.openConnectionImpl(ConnectionFactoryImpl.java:262)
mytbedge_1_f5648ad89a6e | 	at org.postgresql.core.ConnectionFactory.openConnection(ConnectionFactory.java:52)
mytbedge_1_f5648ad89a6e | 	at org.postgresql.jdbc.PgConnection.<init>(PgConnection.java:216)
mytbedge_1_f5648ad89a6e | 	at org.postgresql.Driver.makeConnection(Driver.java:404)
mytbedge_1_f5648ad89a6e | 	at org.postgresql.Driver.connect(Driver.java:272)
mytbedge_1_f5648ad89a6e | 	at com.zaxxer.hikari.util.DriverDataSource.getConnection(DriverDataSource.java:138)
mytbedge_1_f5648ad89a6e | 	at com.zaxxer.hikari.pool.PoolBase.newConnection(PoolBase.java:358)
mytbedge_1_f5648ad89a6e | 	at com.zaxxer.hikari.pool.PoolBase.newPoolEntry(PoolBase.java:206)
mytbedge_1_f5648ad89a6e | 	at com.zaxxer.hikari.pool.HikariPool.createPoolEntry(HikariPool.java:477)
mytbedge_1_f5648ad89a6e | 	at com.zaxxer.hikari.pool.HikariPool.checkFailFast(HikariPool.java:560)
mytbedge_1_f5648ad89a6e | 	at com.zaxxer.hikari.pool.HikariPool.<init>(HikariPool.java:115)
mytbedge_1_f5648ad89a6e | 	at com.zaxxer.hikari.HikariDataSource.getConnection(HikariDataSource.java:112)
mytbedge_1_f5648ad89a6e | 	at org.hibernate.engine.jdbc.connections.internal.DatasourceConnectionProviderImpl.getConnection(DatasourceConnectionProviderImpl.java:122)
mytbedge_1_f5648ad89a6e | 	at org.hibernate.internal.NonContextualJdbcConnectionAccess.obtainConnection(NonContextualJdbcConnectionAccess.java:38)
mytbedge_1_f5648ad89a6e | 	at org.hibernate.resource.jdbc.internal.LogicalConnectionManagedImpl.acquireConnectionIfNeeded(LogicalConnectionManagedImpl.java:108)
mytbedge_1_f5648ad89a6e | 	... 117 common frames omitted
mytbedge_1_f5648ad89a6e | Caused by: java.net.ConnectException: Connection refused (Connection refused)
mytbedge_1_f5648ad89a6e | 	at java.net.PlainSocketImpl.socketConnect(Native Method)
mytbedge_1_f5648ad89a6e | 	at java.net.AbstractPlainSocketImpl.doConnect(AbstractPlainSocketImpl.java:350)
mytbedge_1_f5648ad89a6e | 	at java.net.AbstractPlainSocketImpl.connectToAddress(AbstractPlainSocketImpl.java:206)
mytbedge_1_f5648ad89a6e | 	at java.net.AbstractPlainSocketImpl.connect(AbstractPlainSocketImpl.java:188)
mytbedge_1_f5648ad89a6e | 	at java.net.SocksSocketImpl.connect(SocksSocketImpl.java:392)
mytbedge_1_f5648ad89a6e | 	at java.net.Socket.connect(Socket.java:607)
mytbedge_1_f5648ad89a6e | 	at org.postgresql.core.PGStream.<init>(PGStream.java:61)
mytbedge_1_f5648ad89a6e | 	at org.postgresql.core.v3.ConnectionFactoryImpl.openConnectionImpl(ConnectionFactoryImpl.java:144)
mytbedge_1_f5648ad89a6e | 	... 131 common frames omitted
mytbedge_1_f5648ad89a6e | pg_ctl: could not send stop signal (PID: 10): No such process

Stop and remove containers:

docker compose stop
docker compose rm

Remove postmaster.pid file:

sudo rm -rf ~/.mytb-edge-data/db/postmaster.pid

Start containers again:

docker compose up -d
docker compose logs -f mytbedge

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:
- Overview - Learn about ThingsBoard 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.
- Push data from edge to cloud and vice versa - Learn how to push data from edge to cloud and vice versa.
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.

本页目录