Installing ThingsBoard Edge on Ubuntu Server

This guide provides step-by-step instructions for installing ThingsBoard Edge on Ubuntu 22.04 LTS and Ubuntu 24.04 LTS.

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.

Step 1. Install Java 17 (OpenJDK)

ThingsBoard Edge requires Java 17. To install OpenJDK 17:

sudo apt update && sudo apt install openjdk-17-jdk-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 (...)

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

To install the PostgreSQL database:

# 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, set the password for the main PostgreSQL user:

sudo -u postgres psql -c "\password"

Enter and confirm the password when prompted.

Create a new PostgreSQL database named tb_edge:

echo "CREATE DATABASE tb_edge;" | psql -U postgres -d postgres -h 127.0.0.1 -W

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

To install the PostgreSQL database:

# 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, set the password for the main PostgreSQL user:

sudo -u postgres psql -c "\password"

Create a new PostgreSQL database named tb_edge:

echo "CREATE DATABASE tb_edge;" | psql -U postgres -d postgres -h 127.0.0.1 -W

Cassandra installation

To install Apache Cassandra:

# Add Cassandra repository
echo "deb [signed-by=/etc/apt/keyrings/apache-cassandra.asc] https://debian.cassandra.apache.org 50x main" | sudo tee /etc/apt/sources.list.d/cassandra.sources.list
sudo curl -o /etc/apt/keyrings/apache-cassandra.asc https://downloads.apache.org/cassandra/KEYS
sudo apt-get update
# Cassandra installation
sudo apt-get install -y cassandra cassandra-tools

Verify that Cassandra is running:

nodetool status
sudo systemctl status cassandra.service

The status column in the output should report UN (Up/Normal). You may need to wait a few moments for Cassandra to initialize.

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 3. 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 Ubuntu 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 "export 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 4. Download and install ThingsBoard Edge

wget https://github.com/thingsboard/thingsboard-edge/releases/download/v4.3.1.1/tb-edge-4.3.1.1.deb
sudo dpkg -i tb-edge-4.3.1.1.deb

Step 5. Configure ThingsBoard Edge

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

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 6. Complete the installation

Execute the installation script:

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

Start the service:

sudo service tb-edge start

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

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