Edge
ThingsBoard Documentation
Cloud Professional Edition Community Edition Edge IoT Gateway License Server Trendz Analytics
Try it now Pricing
Installation > Docker (Linux or Mac OS)
Getting Started Documentation
Architecture

On this page

Installing ThingsBoard Edge using Docker (Linux or Mac OS)

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 CE/PE server that supports edge functionality up and running.

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

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 visit this guide Provision edge on CE server or Provision edge on PE server respectively.

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

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.

1
docker pull thingsboard/tb-edge-monolith:3.3.0EDGE

Step 2. Running ThingsBoard Edge

Here you can find ThingsBoard Edge single instance docker image with PostgreSQL database:

Create docker compose file for ThingsBoard Edge service:

1
sudo 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
version: '2.2'

services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge-monolith:3.3.0EDGE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      EDGE_LICENSE_INSTANCE_DATA_FILE: /data/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, demo.thingsboard.io or thingsboard.cloud
    volumes:
      - ~/.mytb-edge-data:/data
      - ~/.mytb-edge-logs:/var/log/tb-edge
      

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
  • thingsboard/tb-edge-monolith:3.3.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.

Please set CLOUD_RPC_HOST with an IP address of the machine where ThingsBoard CE/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.
  • Use X.X.X.X IP address in case edge is connecting to the cloud instance in the same network or in the docker.
  • Or use demo.thingsboard.io if you are connecting edge to ThingsBoard Live Demo for evaluation.

If ThingsBoard Edge is going to be running on the same machine where ThingsBoard Professional Edition/Community Edition server is running you’ll need to update docker compose port mapping.

Please update next lines of docker compose:
ports:
- “18080:8080”
- “11883:1883”
- “15683:5683/udp”

Please make sure ports above are not used by any other application.

Before starting Docker container run following commands to create a directory for storing data and logs and then change its owner to docker container user, to be able to change user, chown command is used, which requires sudo permissions (command will request password for a sudo access):

1
2
$ 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.

Set the terminal in the directory which contains the docker-compose.yml file and execute the following command to up this docker compose directly:

1
2
docker-compose pull
docker-compose up

Step 3. Open ThingsBoard Edge UI

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

If during installation process you have changed edge HTTP_BIND_PORT please use that port instead for Edge UI URL:

http://localhost:HTTP_BIND_PORT

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

Step 4. Detaching, stop and start commands

You can detach from session terminal with Ctrl-p Ctrl-q - 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 node logs execute the following command:

1
docker-compose logs -f mytbedge

To stop the container:

1
docker-compose stop

To start the container:

1
docker-compose start

Troubleshootings

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.

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 container:

1
2
docker-compose stop
docker-compose rm

Remove postmaster.pid file:

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

Start container:

1
docker-compose up

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: