Stop the war

Support Ukraine
Try it now Pricing
PE Edge
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application
Installation > Step 2 - Install instructions > Docker (Linux or Mac OS)
Getting Started Documentation
Architecture API FAQ

On this page

Installing ThingsBoard Edge using Docker (Linux or Mac OS)

Rules of Compatibility Between ThingsBoard Edge and ThingsBoard Server Versions:

  • ThingsBoard Edge version X.Y.Z is compatible with ThingsBoard Server version X.Y.Z and subsequent versions.
  • ThingsBoard Edge version X.Y.Z is NOT compatible with ThingsBoard Server versions prior to X.Y.Z.

Example: ThingsBoard Edge version 3.3.4.1 is compatible with ThingsBoard server version 3.3.4.1 and later 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 earlier versions (3.3.4, 3.3.3, …). In such a case, ThingsBoard Server 3.3.4.1 or an earlier version should 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

ThingsBoard Cloud server

To begin using ThingsBoard Edge, you must have a ThingsBoard PE server supporting edge functionality up and running.

The easiest way is to use ThingsBoard Cloud server.

The alternative option is to install ThingsBoard Professional Edition server on-premise. Please visit Install PE 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

Don’t forget to add your linux user to the docker group. See Manage Docker as a non-root user.

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. Pull ThingsBoard Edge Images

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

1

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

Step 2. 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
28
29

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.

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.

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

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 started, you will be able to open ThingsBoard Edge UI using the following link http://localhost:8080.

Use next ThingsBoard Edge UI link http://localhost:18080 if you updated HTTP 8080 bind port to 18080.

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

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

If you still rely on Docker Compose as docker-compose (with a hyphen) here is the list of the above commands:
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

If you still rely on Docker Compose as docker-compose (with a hyphen) here is the list of the above commands:
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: