- Prerequisites
- Step 1. Running ThingsBoard Edge
- Step 2. Open ThingsBoard Edge UI
- Step 3. Detaching, stop and start commands
- Troubleshooting
- 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 begin using ThingsBoard Edge, you must have a ThingsBoard server supporting edge functionality up and running.
The easiest way is to use Live Demo server.
The alternative option is to install ThingsBoard Community Edition server on-premise. Please visit Install CE to install server.
Edge provision on cloud
Additionally, you will need to provision ThingsBoard Edge on a cloud server. If you haven’t done so yet, please follow the Provision Edge on Cloud guide.
Once the ThingsBoard Edge is provisioned on the cloud server, please follow the installation steps provided below.
Docker installation
Edge Hardware Requirements
The hardware requirements for ThingsBoard Edge depend on the number of devices connected to the edge and the extent of GUI usage locally.
If you’re planning to run ThingsBoard Edge without heavy GUI usage (local dashboards, device management, etc.), and you have a relatively small number of devices (under 100) connected to a single machine, then a minimum of 1GB of RAM should suffice.
On the other hand, if you anticipate heavy GUI usage (local dashboards, device management, etc.) and you’re connecting 100+ devices on a single machine, we recommend having at least 4GB of RAM to ensure optimal performance.
Step 1. Running ThingsBoard Edge
Here you can find ThingsBoard Edge docker image:
Create docker compose file for ThingsBoard Edge service:
1
nano docker-compose.yml
Add the following 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
version: '3.0'
services:
mytbedge:
restart: always
image: "thingsboard/tb-edge:3.6.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.250 or demo.thingsboard.io
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 dirmytb-edge-data
to ThingsBoard Edge DataBase data directory;mytb-edge-logs:/var/log/tb-edge
- mounts the host’s dirmytb-edge-logs
to ThingsBoard Edge logs directory;-
mytb-edge-data/db:/var/lib/postgresql/data
- mounts the host’s dirmytb-edge-data/db
to Postgres data directory; -
thingsboard/tb-edge:3.6.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;
Before starting your Docker containers, execute the following commands to create directories for data storage and logs. These commands will also change the ownership of the newly created directories to the Docker container user.
The chown command is used to change the owner of the directories, and it requires sudo permissions. You may be prompted to enter a password to grant sudo access:
1
mkdir -p ~/.mytb-edge-logs && sudo chown -R 799:799 ~/.mytb-edge-logs
1
mkdir -p ~/.mytb-edge-data && sudo chown -R 799:799 ~/.mytb-edge-data
NOTE: Replace directory ~/.mytb-edge-data
and ~/.mytb-edge-logs
with directories you’re planning to use in 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
2
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.
Please use your tenant credentials from local cloud instance or ThingsBoard Live Demo 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
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.
Database issues
NOTE If you see errors related to edge is not able to connect to database, for example
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
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:
1
2
docker compose stop
docker compose rm
Remove postmaster.pid file:
1
sudo rm -rf ~/.mytb-edge-data/db/postmaster.pid
Start containers again:
1
2
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.