Installing ThingsBoard Edge on CentOS/RHEL

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

Prerequisites

To run ThingsBoard Edge, you need an active ThingsBoard Community Edition account that supports Edge functionality.

You can install a local ThingsBoard CE server. The local server is accessible at http://localhost:8080.

Hardware requirements

The hardware requirements for ThingsBoard Edge depend on the number of connected devices and platform interaction intensity.

Workload	RAM	Description
Light	1 GB	Fewer than 100 devices, minimal dashboard/device management usage
Heavy	4 GB	100+ devices or intense platform interactions

Deploy a new Edge instance

To create a new Edge instance on your ThingsBoard Server:

Sign in to your ThingsBoard instance and go to Edge Management → Instances. Click Add (+) in the top-right corner and select Add new edge.
Enter a name for the Edge, like My New Edge.
Click Add.
Your new Edge instance is created and appears at the top of the list.

Guided installation using ThingsBoard Server instructions

Once an Edge instance is created, the server generates pre-configured installation instructions containing the Edge credentials (Edge Key, Edge Secret, etc.). To access them:

Click the Edge entity to open its details.
Click Install & Connection Instructions.
Select the installation method and follow the instructions to install Edge and connect it to the server.

Manual installation and configuration

If you are unable to use the guided instructions above, follow the steps below to install and configure Edge manually.

Pre-installation

Install the required tools:

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

Step 1. Configure the ThingsBoard Edge database

ThingsBoard Edge supports SQL and hybrid database approaches.

PostgreSQL
Hybrid (PostgreSQL + Cassandra)

PostgreSQL is recommended for development and production environments with moderate load (fewer than 5,000 messages/sec). Many cloud providers offer managed PostgreSQL services, making it a cost-effective option for most deployments.

Update your system:

sudo dnf update

Install the PostgreSQL repository RPM for your OS version:

RHEL/CentOS 8
RHEL/CentOS 9

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

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

Install PostgreSQL and initialize the database. The PostgreSQL service will start automatically on system boot:

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

Set the password for the main PostgreSQL user:

sudo -u postgres psql -c "\password"

Enter and confirm the password when prompted.

Configure MD5 authentication for local connections, then restart PostgreSQL and create the tb_edge database:

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

The hybrid approach is recommended when you plan to manage 1M+ devices in production or handle high data ingestion rates (more than 5,000 messages/sec). In this case, ThingsBoard Edge stores time-series data in Cassandra while using PostgreSQL for primary entities like devices, assets, dashboards, and customers.

PostgreSQL installation

Update your system:

sudo dnf update

Install the PostgreSQL repository RPM for your OS version:

RHEL/CentOS 8
RHEL/CentOS 9

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

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

Install PostgreSQL and initialize the database:

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

Set the password for the main PostgreSQL user:

sudo -u postgres psql -c "\password"

Configure MD5 authentication, restart PostgreSQL, and create the tb_edge database:

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

Cassandra installation

Add the Cassandra repository. Create the repo file:

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

Add the following content:

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

Install and start Cassandra:

sudo yum update
sudo yum install cassandra
sudo service cassandra start

ThingsBoard Edge configuration for hybrid mode

Open the ThingsBoard Edge configuration file:

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

Add the following lines. Replace PUT_YOUR_POSTGRESQL_PASSWORD_HERE with your actual PostgreSQL user password:

# 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

Optionally, add the following parameters to connect to external Cassandra nodes:

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 2. Select the queue service

ThingsBoard Edge can use different messaging systems for storing messages and enabling communication between its services.

In Memory
Kafka (recommended)

The In Memory queue is the built-in default implementation. It is suitable for development or proof-of-concept environments, but is not recommended for production or clustered deployments due to limited scalability.

No additional configuration is required.

Kafka is recommended for production deployments and is used in most ThingsBoard production environments. It provides high throughput, durability, and horizontal scalability.

Install Docker for CentOS/RHEL if you have not done so already.

To install Kafka in a Docker container, run the following command. It creates a docker-compose-kafka.yml file and starts the container:

cat > docker-compose-kafka.yml <<EOF && docker compose -f docker-compose-kafka.yml up -d
services:
  kafka:
    restart: always
    image: bitnamilegacy/kafka:4.0
    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

Configure ThingsBoard Edge to use Kafka:

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

Replace localhost:9092 with your actual Kafka bootstrap server address if necessary.

Step 3. Download and install ThingsBoard Edge

wget https://github.com/thingsboard/thingsboard-edge/releases/download/v4.3.1.1/tb-edge-4.3.1.1.rpm
sudo rpm -Uvh tb-edge-4.3.1.1.rpm

Step 4. Configure ThingsBoard Edge

ThingsBoard Edge requires Java 17. To install OpenJDK 17:

sudo dnf install java-17-openjdk-headless

Configure your operating system to use OpenJDK 17 by default:

sudo update-alternatives --config java

Verify the installation:

java -version

The expected output:

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

In the Edge instance details panel, click Copy Edge Key and Copy Edge Secret. Store these values — you need them in the next step.

Copy Edge Key and Edge Secret from the instance details panel

Edit the ThingsBoard Edge configuration file to set your Edge credentials and cloud connection parameters.

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
EOL'

Configuration parameters:

Parameter	Description
`CLOUD_ROUTING_KEY`	Your Edge key (copied above)
`CLOUD_ROUTING_SECRET`	Your Edge secret (copied above)
`CLOUD_RPC_HOST`	Hostname or IP address of the ThingsBoard Server
`CLOUD_RPC_PORT`	gRPC port used for Edge–server communication (default: 7070)
`CLOUD_RPC_SSL_ENABLED`	Set to `true` to enable SSL — required when connecting to ThingsBoard Cloud
`HTTP_BIND_PORT`	Local HTTP port for the Edge UI (18080 avoids conflict with ThingsBoard Server on 8080)
`MQTT_BIND_PORT`	Local MQTT port (11883 avoids conflict with ThingsBoard Server on 1883)
`COAP_BIND_PORT`	Local CoAP port (15683 avoids conflict with ThingsBoard Server on 5683)

If you changed the default PostgreSQL credentials, add the following to /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

Step 5. Complete the installation

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

sudo /usr/share/tb-edge/bin/install/install.sh

Start the ThingsBoard Edge service:

sudo service tb-edge start

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

Log in using the same default credentials listed in the Prerequisites section. You can change them in the Edge UI after logging in.

Troubleshooting

ThingsBoard Edge logs are stored in:

/var/log/tb-edge

To check for errors:

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

Service management

To stop the ThingsBoard Edge service:

sudo service tb-edge stop

To restart the ThingsBoard Edge service:

sudo service tb-edge restart

To check the status of the ThingsBoard Edge service:

sudo service tb-edge status