Stand with Ukraine flag
Try it now Pricing
Edge
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Installation > On premise > Ubuntu Server
Getting Started Documentation Devices Library
Architecture API FAQ
On this page

Installing ThingsBoard Edge on Ubuntu Server

doc warn icon

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 describes how to install ThingsBoard Edge on Ubuntu 18.04 LTS / Ubuntu 20.04 LTS.

Prerequisites

To start using the ThingsBoard Edge, it is essential to have a running ThingsBoard server that supports Edge functionality.

The easiest way is to use the Live Demo server.

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

Edge Hardware Requirements

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

  • Light Usage: If you intend to operate ThingsBoard Edge with minimal GUI interactions (such as local dashboards and device management) and expect to connect fewer than 100 devices to a single machine, at least 1GB of RAM should be sufficient.

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

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

  • Enter a name for your Edge. For instance, “My New Edge”. Click “Add” to confirm the addition of your new Edge.

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

Log in to your ThingsBoard PE instance and navigate to the Edge Management -> Instances section. Click the "+" icon in the top right corner and select "Add new edge".

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

Enter a name for your Edge. For instance, "My New Edge". Click "Add" to confirm the addition of your new Edge.

Enter a name for your Edge. For instance, “My New Edge”. Click “Add” to confirm the addition of your new Edge.

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

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

Guided Installation Using ThingsBoard Server Pre-configured Instructions

The easiest way to install and connect the Edge to the Server is to follow the installation instructions provided by the ThingsBoard Server. For every Edge Entity, the Server displays the instructions with pre-populated fields such as the Edge secret key, Edge routing key, Edge RPC host URI, and so on

Please follow the steps below to use these prepared instructions:

  • Click an Edge entity row to open its details;

  • Click on the “Install & Connect Instructions” button;

  • Follow the instructions to install Edge and connect to the server.

Click an Edge entity row to open its details;

Click an Edge entity row to open its details;

Click on the "Install & Connect Instructions" button;

Click on the “Install & Connect Instructions” button;

Follow the instructions to install Edge and connect to the server.

Follow the instructions to install Edge and connect to the server.

Manual Installation and Configuration

If for any reason you are unable to use the prepared ThingsBoard Server Instructions above, please follow the steps below. These steps will guide you through installing and configuring the Edge by yourself.

Step 1. Install Java 17 (OpenJDK)

ThingsBoard service is running on Java 17. Follow this instructions to install OpenJDK 17:

1
2

sudo apt update
sudo apt install openjdk-17-jdk

Please don’t forget to configure your operating system to use OpenJDK 17 by default. You can configure which version is the default using the following command:

1

sudo update-alternatives --config java

You can check the installation using the following command:

1

java -version

Expected command output is:

1
2
3

openjdk version "17.x.xx" 
OpenJDK Runtime Environment (...)
OpenJDK 64-Bit Server VM (...)

Step 2. Configure ThingsBoard Edge Database

ThingsBoard Edge supports SQL and hybrid database approaches. See the architecture page for details.

PostgreSQL (recommended for < 5K msg/sec)
Hybrid
PostgreSQL+Cassandra
(recommended for > 5K msg/sec)
Doc info icon

The ThingsBoard team recommends using PostgreSQL for development and production environments with moderate load (less than 5000 msg/sec). Many cloud providers offer managed PostgreSQL services, making it a cost-effective solution for most ThingsBoard deployments.

ThingsBoard Edge uses PostgreSQL database as a local storage.

The following instructions will help you install PostgreSQL:

1
2
3
4
5
6
7
8

# Automated repository configuration:
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

# install and launch the postgresql service:
sudo apt update
sudo apt -y install postgresql-16
sudo service postgresql start

Once PostgreSQL is installed, you may want to create a new user or set the password for the main user. The following instructions will help you to set the password for the main PostgreSQL user.

To switch your current user context to the postgres user, execute the following script:

1

sudo su - postgres

To interact with the PostgreSQL database, enter:

1

psql

You will connect to the database as the main PostgreSQL user. To set the password, enter the following command after postgres=# :

1

\password

Enter and confirm the password. Then, press “Ctrl+D” to return to the main user console.

Connect to the “postgres” database as the “postgres” user:

1

psql -U postgres -d postgres -h 127.0.0.1 -W

Create the ThingsBoard Edge database and name it “tb_edge” :

1

CREATE DATABASE tb_edge;

Press “Ctrl+D” twice to quit PostgreSQL.

Doc info icon

The ThingsBoard team recommends using a hybrid database approach if you plan to manage 1M+ devices in production or handle high data ingestion rate (more than 5000 msg/sec). In this case, ThingsBoard Edge stores time-series data in Cassandra while continuing to use PostgreSQL for primary entities such as devices, assets, dashboards, and customers.

PostgreSQL Installation

The following instructions will help you install PostgreSQL:

1
2
3
4
5
6
7
8

# Automated repository configuration:
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

# install and launch the postgresql service:
sudo apt update
sudo apt -y install postgresql-16
sudo service postgresql start

Once PostgreSQL is installed, you may want to create a new user or set the password for the main user. The following instructions will help you to set the password for the main PostgreSQL user.

To switch your current user context to the postgres user, execute the following script:

1

sudo su - postgres

To interact with the PostgreSQL database, enter:

1

psql

You will connect to the database as the main PostgreSQL user. To set the password, enter the following command after postgres=# :

1

\password

Enter and confirm the password. Then, press “Ctrl+D” to return to the main user console.

Connect to the “postgres” database as the “postgres” user:

1

psql -U postgres -d postgres -h 127.0.0.1 -W

Create the ThingsBoard Edge database and name it “tb_edge” :

1

CREATE DATABASE tb_edge;

Press “Ctrl+D” twice to quit PostgreSQL.

Cassandra Installation

The instructions listed below will help you to install Cassandra.

1
2
3
4
5
6
7
8

# Add cassandra repository
echo "deb https://debian.cassandra.apache.org 41x main" | sudo tee /etc/apt/sources.list.d/cassandra.sources.list
curl https://downloads.apache.org/cassandra/KEYS | sudo apt-key add -
sudo apt-get update
## Cassandra installation
sudo apt-get install cassandra
## Tools installation
sudo apt-get install cassandra-tools

In order to run Cassandra, install Java 11.

Install the package:

1

sudo apt install openjdk-11-jdk

Set Java 17 as the default version (required for ThingsBoard Edge):

1

sudo update-alternatives --config java

Edit the Cassandra configuration file:

1

sudo nano /usr/share/cassandra/cassandra.in.sh

Find the following line:

1
2

# JAVA_HOME can optionally be set here
#JAVA_HOME=/usr/local/jdk6

And replace it as follows:

1
2

# JAVA_HOME can optionally be set here
JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

Then, restart Cassandra:

1

sudo service cassandra stop

1

sudo service cassandra start
ThingsBoard Edge Configuration

Edit ThingsBoard Edge configuration file:

1

sudo nano /etc/tb-edge/conf/tb-edge.conf

Add the following lines to the configuration file. Don’t forget to replace “PUT_YOUR_POSTGRESQL_PASSWORD_HERE” with your real postgres user password:

1
2
3
4
5

# DB Configuration 
export DATABASE_TS_TYPE=cassandra
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/tb_edge
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=PUT_YOUR_POSTGRESQL_PASSWORD_HERE

You can optionally add the following parameters to reconfigure your Edge instance to connect to external Cassandra nodes:

1
2
3
4
5
6

export CASSANDRA_CLUSTER_NAME=Edge Cluster
export CASSANDRA_KEYSPACE_NAME=thingsboard
export CASSANDRA_URL=127.0.0.1:9042
export CASSANDRA_USE_CREDENTIALS=false
export CASSANDRA_USERNAME=
export CASSANDRA_PASSWORD=

Step 3. Choose Queue Service

ThingsBoard Edge can use different messaging systems and brokers for storing messages and enabling communication between its services. Choose the appropriate queue implementation based on your specific business needs:

  • In Memory: The built-in and default queue implementation. It is useful for development or proof-of-concept (PoC) environments, but is not recommended for production or any type of clustered deployments due to limited scalability.

  • Kafka: Recommended for production deployments. This queue is used in the most of ThingsBoard production environments now.

In Memory (built-in and default)
Kafka (recommended for on-prem, production installations)
Kafka in docker container (recommended for on-prem, production installations)

In Memory queue is built in and enabled by default. No additional configuration is required.

Kafka Installation

Apache Kafka is an open source stream processing platform.

Doc info icon

Kafka can be run on either ThingsBoard Server or ThingsBoard Edge. However, it is not possible to run Kafka on both services simultaneously, as this would create conflicts or inefficiencies.

Install ZooKeeper

Kafka uses ZooKeeper so you need to first install ZooKeeper server:

1

sudo apt-get install zookeeper
Setup ZooKeeper Systemd Unit file

Create systemd unit file for Zookeeper:

1

sudo nano /etc/systemd/system/zookeeper.service

Add below content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

[Unit]
Description=Apache Zookeeper server
Documentation=http://zookeeper.apache.org
Requires=network.target remote-fs.target
After=network.target remote-fs.target

[Service]
Type=simple
ExecStart=/usr/local/kafka/bin/zookeeper-server-start.sh /usr/local/kafka/config/zookeeper.properties
ExecStop=/usr/local/kafka/bin/zookeeper-server-stop.sh
Restart=on-abnormal

[Install]
WantedBy=multi-user.target
Enable and start ZooKeeper:
1

sudo systemctl enable --now zookeeper
Install Kafka
1
2
3
4
5

wget https://downloads.apache.org/kafka/3.8.1/kafka_2.13-3.8.1.tgz

tar -xzf kafka_2.13-3.8.1.tgz

sudo mv kafka_2.13-3.8.1 /usr/local/kafka
Setup Kafka Systemd Unit file

Create systemd unit file for Kafka:

1

sudo nano /etc/systemd/system/kafka.service

Add the below content. Make sure to replace “PUT_YOUR_JAVA_PATH” with your real JAVA_HOME path as per the Java installed on your system, by default like “/usr/lib/jvm/java-11-openjdk-xxx”:

1
2
3
4
5
6
7
8
9
10
11
12
13

[Unit]
Description=Apache Kafka Server
Documentation=http://kafka.apache.org/documentation.html
Requires=zookeeper.service

[Service]
Type=simple
Environment="JAVA_HOME=PUT_YOUR_JAVA_PATH"
ExecStart=/usr/local/kafka/bin/kafka-server-start.sh /usr/local/kafka/config/server.properties
ExecStop=/usr/local/kafka/bin/kafka-server-stop.sh

[Install]
WantedBy=multi-user.target
Enable and start Kafka:
1

sudo systemctl enable --now kafka
ThingsBoard Configuration

Edit the ThingsBoard Edge configuration file:

1

sudo nano /etc/tb-edge/conf/tb-edge.conf

Add the following line to the tb-edge.conf file. Make sure to replace “localhost:9092” with your real Kafka bootstrap servers if necessary:

1
2

export TB_QUEUE_TYPE=kafka
export TB_KAFKA_SERVERS=localhost:9092

Kafka Installation

Apache Kafka is an open source stream processing platform.

To install Kafka in a Docker container, follow the instructions below:

1

nano docker-compose-kafka.yml

Add the following lines to the docker-compose-kafka.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

version: '3.8'
services:
  kafka:
    restart: always
    image: bitnami/kafka:3.8.1
    ports:
      - 9092:9092 #to localhost:9092 from host machine
      - 9093 #for Kraft
      - 9094 #to kafka:9094 from within Docker network
    environment:
      ALLOW_PLAINTEXT_LISTENER: "yes"
      KAFKA_CFG_LISTENERS: "OUTSIDE://:9092,CONTROLLER://:9093,INSIDE://:9094"
      KAFKA_CFG_ADVERTISED_LISTENERS: "OUTSIDE://localhost:9092,INSIDE://kafka:9094"
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "INSIDE:PLAINTEXT,OUTSIDE:PLAINTEXT,CONTROLLER:PLAINTEXT"
      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "INSIDE"
      KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE: "false"
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
      KAFKA_CFG_PROCESS_ROLES: "controller,broker" #KRaft
      KAFKA_CFG_NODE_ID: "0" #KRaft
      KAFKA_CFG_CONTROLLER_LISTENER_NAMES: "CONTROLLER" #KRaft
      KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: "0@kafka:9093" #KRaft
    volumes:
      - kafka-data:/bitnami
volumes:
  kafka-data:
    driver: local

Start the container:

1

docker compose -f docker-compose-kafka.yml up -d
ThingsBoard Edge Configuration

Edit ThingsBoard Edge configuration file:

1

sudo nano /etc/tb-edge/conf/tb-edge.conf

Add the following line to the configuration file. Replace “localhost:9092” with your real Kafka bootstrap servers if needed:

1
2

export TB_QUEUE_TYPE=kafka
export TB_KAFKA_SERVERS=localhost:9092

Step 4. ThingsBoard Edge Service Installation

Download the installation package.

1

wget https://github.com/thingsboard/thingsboard-edge/releases/download/v3.9/tb-edge-3.9.deb

Go to the download repository and install ThingsBoard Edge service

1

sudo dpkg -i tb-edge-3.9.deb

Step 5. Configure ThingsBoard Edge

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.

Edit the ThingsBoard Edge configuration file:

1

sudo nano /etc/tb-edge/conf/tb-edge.conf

Update the following lines in your configuration file. Be sure to replace:

  • “PUT_YOUR_POSTGRESQL_PASSWORD_HERE” replace with your actual postgres user password.

  • “PUT_YOUR_CLOUD_IP” replace with an IP address of the machine running ThingsBoard Server. This depends on your setup:

    • If you’re connecting the Edge to the ThingsBoard Live Demo for evaluation, use demo.thingsboard.io.

    • Use localhost if the Edge is running on the same machine as the Server instance.
    • Use an X.X.X.X IP address if the Edge is connecting to the Server instance in the same network or in a Docker container.
  • Replace “PUT_YOUR_EDGE_KEY_HERE” and “PUT_YOUR_EDGE_SECRET_HERE” with the appropriate Edge key and secret:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# UNCOMMENT NEXT LINES AND PUT YOUR CLOUD CONNECTION SETTINGS:
# export CLOUD_ROUTING_KEY=PUT_YOUR_EDGE_KEY_HERE
# export CLOUD_ROUTING_SECRET=PUT_YOUR_EDGE_SECRET_HERE

# UNCOMMENT NEXT LINES IF EDGE CONNECTS TO CE 'DEMO.THINGSBOARD.IO' SERVER:
# export CLOUD_RPC_HOST=demo.thingsboard.io

# UNCOMMENT NEXT LINES IF YOU ARE RUNNING EDGE ON THE SAME MACHINE WHERE THINGSBOARD SERVER IS RUNNING:
# export HTTP_BIND_PORT=18080
# export MQTT_BIND_PORT=11883
# export COAP_BIND_PORT=15683
# export LWM2M_ENABLED=false
# export SNMP_ENABLED=false

# UNCOMMENT NEXT LINES IF YOU CHANGED DEFAULT CLOUD RPC HOST/PORT SETTINGS:
# export CLOUD_RPC_HOST=PUT_YOUR_CLOUD_IP
# export CLOUD_RPC_PORT=7070


# UNCOMMENT NEXT LINES IF YOU HAVE CHANGED DEFAULT POSTGRESQL DATASOURCE SETTINGS:
# export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/tb_edge
# export SPRING_DATASOURCE_USERNAME=postgres
# export SPRING_DATASOURCE_PASSWORD=PUT_YOUR_POSTGRESQL_PASSWORD_HERE
Doc info icon

To run ThingsBoard Edge on the same machine as the ThingsBoard Server, update the configuration parameters to avoid port collision between them. Uncomment the corresponding lines in the tb-edge.conf file.

Ensure that other applications do not use the 18080, 11883, and 15683 ports.

Step 6. Run installation Script

Once ThingsBoard Edge is installed and configured please execute the following installation script:

1

sudo /usr/share/tb-edge/bin/install/install.sh
Doc info icon

Make sure you run this script from the root. To change the current directory to the root directory, run the command cd /.

Step 7. Restart ThingsBoard Edge Service

1

sudo service tb-edge restart

Step 8. Open ThingsBoard Edge UI

Once the Edge service is started, open the Edge UI at http://localhost:8080.

Doc info icon

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

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

Troubleshooting

ThingsBoard Edge logs stored in the following directory:

1

/var/log/tb-edge

You can issue the following command in order to check if there are any errors on the service side:

1

cat /var/log/tb-edge/tb-edge.log | grep ERROR

Start edge service:

1

sudo service tb-edge start

Stop edge service:

1

sudo service tb-edge stop

Restart edge service:

1

sudo service tb-edge restart

Check status of ThingsBoard Edge service:

1

sudo service tb-edge status

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: