Stand with Ukraine flag
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 MQTT Broker
Installation > On premise > CentOS/RHEL Server
Getting Started Documentation Devices Library
Architecture API FAQ
On this page

Installing ThingsBoard Edge on CentOS/RHEL Server

Before installing ThingsBoard Edge, ensure that ThingsBoard Server is installed and updated to the latest version.

Additionally, verify that the ThingsBoard Edge and ThingsBoard Server versions are compatible.

doc warn icon

Version Compatibility Rules:

  • ThingsBoard Edge version X.Y.Z works with the ThingsBoard Server version X.Y.Z and the next two versions.

ThingsBoard Edge 3.8.0 works with ThingsBoard Server 3.8.0 and two later versions (3.9.0 and 3.9.1). You can view the ThingsBoard Server Release Notes here.

  • ThingsBoard Edge version X.Y.Z does not work with older ThingsBoard Server versions.

ThingsBoard Edge 3.9.1 does not support ThingsBoard Server 3.8.0 or any earlier versions. In such cases, the ThingsBoard Server must be upgraded to the latest version first.

Doc info icon

If you run an older version of ThingsBoard Edge (e.g., version 3.6.0), the ThingsBoard team cannot guarantee the availability or proper functioning of all features.

This guide provides step-by-step instructions for installing ThingsBoard Edge on RHEL/CentOS 7 and 8.

Prerequisites

To start running ThingsBoard Professional Edition Edge, you will need an active ThingsBoard Professional Edition account that supports Edge functionality.

ThingsBoard Cloud
Local Server

Sign up for a ThingsBoard Cloud account, which is the easiest way to get started. Throughout the rest of this tutorial, this URL will be referred to as SERVER_URL

Log in using your ThingsBoard Cloud tenant credentials.

You can install the ThingsBoard Professional Edition local server. For this, please refer to the ThingsBoard installation guide.

The local server can be accessed via http://localhost:8080. Throughout this tutorial, we will refer to this URL as SERVER_URL. Log in with:

Edge Hardware Requirements

The hardware requirements for ThingsBoard Edge are determined by the number of connected devices and the intensity of interactions with the platform interface. To ensure optimal performance, we recommend the following:

  • At least 1GB of RAM (Light workload): It is suitable for minimal interactions with the platform interface, such as dashboards and device management, and fewer than 100 connected devices.
  • At least 4GB of RAM (Heavy workload): This configuration is suitable for intense platform interactions and 100+ devices connected to a single machine.

Deploying a New Edge Instance

To create a new Edge:

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

  • Enter a name for the Edge you are creating. For example, “My New Edge”. If needed, update the cloud endpoint.

    • If the Edge runs in a Docker container, do not use “localhost” as the endpoint. Instead, use the IP address of the machine where ThingsBoard PE is hosted and accessible by the Edge container. For example, http://10.7.2.143:8080.
    • If you are using the ThingsBoard Cloud, there’s no need to change this setting — keep it as is.
    • Click the “Add” button to confirm the addition of the Edge instance.

  • Your new Edge is created and will appear at the top of the list, as entries are sorted by creation time by default.

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

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

Enter a name for the Edge you are creating. For example, "My New Edge". If needed, update the cloud endpoint. If the Edge runs in a [Docker container](https://docs.docker.com/get-started/docker-overview/){:target="_blank"}, do not use “localhost” as the endpoint. Instead, use the IP address of the machine where ThingsBoard PE is hosted and accessible by the Edge container. For example, http://10.7.2.143:8080. If you are using the ThingsBoard Cloud, there’s no need to change this setting — keep it as is. Click the "Add" button to confirm the addition of the Edge instance.

Enter a name for the Edge you are creating. For example, “My New Edge”. If needed, update the cloud endpoint.

  • If the Edge runs in a Docker container, do not use “localhost” as the endpoint. Instead, use the IP address of the machine where ThingsBoard PE is hosted and accessible by the Edge container. For example, http://10.7.2.143:8080.
  • If you are using the ThingsBoard Cloud, there’s no need to change this setting — keep it as is.
  • Click the “Add” button to confirm the addition of the Edge instance.
Your new Edge is created and will appear at the top of the list, as entries are sorted by creation time by default.

Your new Edge is created and will appear at the top of the list, as entries are sorted by creation time by default.

Guided Installation Using ThingsBoard Server Pre-configured Instructions

Once the Edge instance has been created, the installation instructions will be available for use. Each Edge has preset configurations that contain important credentials, such as Edge Secret, Edge Key, etc. To access these configurations:

  • Click on the Edge entity to open its details.

  • Click the “Install & Connection Instructions” button.

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

Click on the Edge entity to open its details.

Click on the Edge entity to open its details.

Click the "Install & Connection Instructions" button.

Click the “Install & Connection Instructions” button.

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

Follow the instructions to install Edge and connect it 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.

Pre-installation step

Before continue to installation execute the following commands in order to install necessary tools:

1

sudo yum install -y nano wget && sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

Step 1. Install Java 17 (OpenJDK)

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

1

sudo dnf install java-17-openjdk

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 (build ...)

Step 2. Configure ThingsBoard 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.

To install PostgreSQL, follow the instructions below.

Update your system:

1

sudo dnf update

Install the repository RPM:

  • For CentOS/RHEL 8:
1

sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
  • For CentOS/RHEL 9:
1

sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm

Install packages and initialize PostgreSQL. The PostgreSQL service will automatically start every time the system boots up.

1
2
3
4

sudo dnf -qy module disable postgresql && \
sudo dnf -y install postgresql16 postgresql16-server postgresql16-contrib && \
sudo /usr/pgsql-16/bin/postgresql-16-setup initdb && \
sudo systemctl enable --now postgresql-16

Once PostgreSQL is installed, it is recommended to set the password for the PostgreSQL main user.

The following command will switch the current user to the PostgreSQL user and set the password directly in PostgreSQL.

1

sudo -u postgres psql -c "\password"

Then, enter and confirm the password.

Modify PostgreSQL’s Authentication Method (Optional)

Since ThingsBoard Edge uses the PostgreSQL database for local storage, configuring MD5 authentication ensures that only authenticated users or applications can access the database, thus protecting your data. After configuring the password, edit the pg_hba.conf file to use MD5 hashing for authentication instead of the default method (ident) for local IPv4 connections.

To replace ident with md5, run the following command:

1

sudo sed -i 's/^host\s\+all\s\+all\s\+127\.0\.0\.1\/32\s\+ident/host    all             all             127.0.0.1\/32            md5/' /var/lib/pgsql/16/data/pg_hba.conf

Then run the command that will restart the PostgreSQL service to apply configuration changes, connect to the database as a postgres user, and create the ThingsBoard Edge database (tb_edge). To connect to the PostgreSQL database, enter the PostgreSQL password.

1

sudo systemctl restart postgresql-16.service && psql -U postgres -d postgres -h 127.0.0.1 -W -c "CREATE DATABASE tb_edge;"
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

To install PostgreSQL, follow the instructions below.

Update your system:

1

sudo dnf update

Install the repository RPM:

  • For CentOS/RHEL 8:
1

sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
  • For CentOS/RHEL 9:
1

sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm

Install packages and initialize PostgreSQL. The PostgreSQL service will automatically start every time the system boots up.

1
2
3
4

sudo dnf -qy module disable postgresql && \
sudo dnf -y install postgresql16 postgresql16-server postgresql16-contrib && \
sudo /usr/pgsql-16/bin/postgresql-16-setup initdb && \
sudo systemctl enable --now postgresql-16

Once PostgreSQL is installed, it is recommended to set the password for the PostgreSQL main user.

The following command will switch the current user to the PostgreSQL user and set the password directly in PostgreSQL.

1

sudo -u postgres psql -c "\password"

Then, enter and confirm the password.

Modify PostgreSQL’s Authentication Method (Optional)

Since ThingsBoard Edge uses the PostgreSQL database for local storage, configuring MD5 authentication ensures that only authenticated users or applications can access the database, thus protecting your data. After configuring the password, edit the pg_hba.conf file to use MD5 hashing for authentication instead of the default method (ident) for local IPv4 connections.

To replace ident with md5, run the following command:

1

sudo sed -i 's/^host\s\+all\s\+all\s\+127\.0\.0\.1\/32\s\+ident/host    all             all             127.0.0.1\/32            md5/' /var/lib/pgsql/16/data/pg_hba.conf

Then run the command that will restart the PostgreSQL service to apply configuration changes, connect to the database as a postgres user, and create the ThingsBoard Edge database (tb_edge). To connect to the PostgreSQL database, enter the PostgreSQL password.

1

sudo systemctl restart postgresql-16.service && psql -U postgres -d postgres -h 127.0.0.1 -W -c "CREATE DATABASE tb_edge;"
Cassandra Installation

In order to run Cassandra, install Java 11:

1

sudo apt install openjdk-11-jdk

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

1

sudo update-alternatives --config java

Add the Cassandra repository:

1

sudo nano /etc/yum.repos.d/cassandra.repo

Add the following content:

1
2
3
4
5
6

[cassandra]
name=Apache Cassandra
baseurl=https://redhat.cassandra.apache.org/50x/
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://downloads.apache.org/cassandra/KEYS
  • 50x for Cassandra 5.0 version series.

Update package index if necessary:

1

sudo yum update

Install Cassandra:

1

sudo yum install cassandra

Start Cassandra service:

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 ThingsBoard 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 is able to use different messaging systems/brokers for storing the messages and communication between ThingsBoard services. How to choose the right queue implementation?

  • In Memory queue implementation is built-in and default. It is useful for development(PoC) environments and is not suitable for production deployments or any sort of cluster deployments.

  • Kafka is recommended for production deployments. This queue is used on the most of ThingsBoard production environments now.

In Memory (built-in and default)
Kafka (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.

To install Kafka in a Docker container, run the command below. It creates docker-compose-kafka.yml, fills it with configuration lines, and starts the container.

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
30

cat > docker-compose-kafka.yml <<EOF && docker compose -f docker-compose-kafka.yml up -d
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
EOF
ThingsBoard Edge Configuration

Edit the ThingsBoard Edge configuration file (tb-edge.conf):

1

echo -e "\nexport TB_QUEUE_TYPE=kafka\nexport TB_KAFKA_SERVERS=localhost:9092" | sudo tee -a /etc/tb-edge/conf/tb-edge.conf > /dev/null

Step 4. ThingsBoard Edge Service Installation

Download installation package.

1

wget https://dist.thingsboard.io/tb-edge-3.9.1pe.rpm

Go to the download repository and install ThingsBoard Edge service

1

sudo rpm -Uvh tb-edge-3.9.1pe.rpm

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
2
3
4
5
6
7
8

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf
export CLOUD_ROUTING_KEY=<PUT_YOUR_EDGE_KEY_HERE>
export CLOUD_ROUTING_SECRET=<PUT_YOUR_EDGE_SECRET_HERE>
export CLOUD_RPC_HOST=thingsboard.cloud
export CLOUD_RPC_PORT=7070
export CLOUD_RPC_SSL_ENABLED=true
export INTEGRATIONS_RPC_PORT=19090
EOL'

1
2
3
4
5
6
7
8

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf
export CLOUD_ROUTING_KEY=<PUT_YOUR_EDGE_KEY_HERE>
export CLOUD_ROUTING_SECRET=<PUT_YOUR_EDGE_SECRET_HERE>
export CLOUD_RPC_HOST=eu.thingsboard.cloud
export CLOUD_RPC_PORT=7070
export CLOUD_RPC_SSL_ENABLED=true
export INTEGRATIONS_RPC_PORT=19090
EOL'

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

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf
export CLOUD_ROUTING_KEY=<PUT_YOUR_EDGE_KEY_HERE>
export CLOUD_ROUTING_SECRET=<PUT_YOUR_EDGE_SECRET_HERE>
export CLOUD_RPC_HOST=<PUT_YOUR_RPC_HOST>
export CLOUD_RPC_PORT=7070
export CLOUD_RPC_SSL_ENABLED=false
export HTTP_BIND_PORT=18080
export MQTT_BIND_PORT=11883
export COAP_BIND_PORT=15683
export LWM2M_ENABLED=false
export SNMP_ENABLED=false
export INTEGRATIONS_RPC_PORT=19090
EOL'
  • PUT_YOUR_EDGE_KEY_HERE: Replace with your actual Edge Key.
  • PUT_YOUR_EDGE_SECRET_HERE: Replace with your actual Edge Secret.
  • PUT_YOUR_RPC_HOST:
    • 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.

Configure PostgreSQL (Optional)

If you changed PostgreSQL default datasource settings, use the following command:

1
2
3
4
5

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/tb_edge
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=<PUT_YOUR_POSTGRESQL_PASSWORD_HERE>
EOL'
  • PUT_YOUR_POSTGRESQL_PASSWORD_HERE: Replace with your actual PostgreSQL user password.

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 the Edge HTTP bind port was changed to 18080 during Edge installation, access the ThingsBoard Edge instance at http://localhost:18080.

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

Troubleshooting

ThingsBoard Edge logs are 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: