Star
Try it now
Solutions
Customers
Use Cases
Partners
About Us
Pricing Docs Guides

Installation

Documentation for installation and configuration of ThingsBoard IoT Platform.

Installing ThingsBoard CE on CentOS/RHEL

Prerequisites

This guide describes how to install ThingsBoard on RHEL/CentOS 7/8. Hardware requirements depend on chosen database and amount of devices connected to the system. To run ThingsBoard and PostgreSQL on a single machine you will need at least 1Gb of RAM. To run ThingsBoard and Cassandra on a single machine you will need at least 8Gb of RAM.

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

For CentOS 7:

# Install wget
sudo yum install -y nano wget
# Add latest EPEL release for CentOS 7
sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

For CentOS 8:

# Install wget
sudo yum install -y nano wget
# Add latest EPEL release for CentOS 8
sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

Step 1. Install Java 8 (OpenJDK)

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

sudo yum install java-1.8.0-openjdk

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

sudo update-alternatives --config java

You can check the installation using the following command:

java -version

Expected command output is:

openjdk version "1.8.0_xxx"
OpenJDK Runtime Environment (...)
OpenJDK 64-Bit Server VM (build ...)

Step 2. ThingsBoard service installation

Download installation package.

wget https://github.com/thingsboard/thingsboard/releases/download/v3.0.1/thingsboard-3.0.1.rpm

Install ThingsBoard as a service

sudo rpm -Uvh thingsboard-3.0.1.rpm

Step 3. Configure ThingsBoard database

ThingsBoard is able to use SQL or hybrid database approach. See corresponding architecture page for more details.

PostgreSQL (recommended for < 5K msg/sec)
Hybrid
PostgreSQL+Cassandra
(recommended for > 5K msg/sec)
Hybrid
PostgreSQL+TimescaleDB
(for TimescaleDB professionals)

ThingsBoard team recommends to use PostgreSQL for development and production environments with reasonable load (< 5000 msg/sec). Many cloud vendors support managed PostgreSQL servers which is a cost-effective solution for most of ThingsBoard instances.

PostgreSQL Installation

Instructions listed below will help you to install PostgreSQL.

# Update your system
sudo yum update

For CentOS 7:

# Install the repository RPM (for CentOS 7):
sudo yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# Install packages
sudo yum -y install epel-release yum-utils
sudo yum-config-manager --enable pgdg12
sudo yum install postgresql12-server postgresql12
# Initialize your PostgreSQL DB
sudo /usr/pgsql-12/bin/postgresql-12-setup initdb
sudo systemctl start postgresql-12
# Optional: Configure PostgreSQL to start on boot
sudo systemctl enable --now postgresql-12

For CentOS 8:

# Install the repository RPM (for CentOS 8):
sudo yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# Install packages
sudo dnf -qy module disable postgresql
sudo dnf -y install postgresql12 postgresql12-server
# Initialize your PostgreSQL DB
sudo /usr/pgsql-12/bin/postgresql-12-setup initdb
sudo systemctl start postgresql-12
# Optional: Configure PostgreSQL to start on boot
sudo systemctl enable --now postgresql-12

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

sudo su - postgres
psql
\password
\q

Then, press “Ctrl+D” to return to main user console.

After configuring the password, edit the pg_hba.conf to use MD5 authentication with the postgres user.

Edit pg_hba.conf file:

sudo nano /var/lib/pgsql/12/data/pg_hba.conf

Locate the following lines:

# IPv4 local connections:
host    all             all             127.0.0.1/32            ident

Replace ident with md5:

host    all             all             127.0.0.1/32            md5

Finally, you should restart the PostgreSQL service to initialize the new configuration:

sudo systemctl restart postgresql-12.service

Connect to the database to create thingsboard DB:

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

Execute create database statement

CREATE DATABASE thingsboard;
\q
ThingsBoard Configuration

Edit ThingsBoard configuration file

sudo nano /etc/thingsboard/conf/thingsboard.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:

# DB Configuration 
export DATABASE_ENTITIES_TYPE=sql
export DATABASE_TS_TYPE=sql
export SPRING_JPA_DATABASE_PLATFORM=org.hibernate.dialect.PostgreSQLDialect
export SPRING_DRIVER_CLASS_NAME=org.postgresql.Driver
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/thingsboard
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=PUT_YOUR_POSTGRESQL_PASSWORD_HERE
export SPRING_DATASOURCE_MAXIMUM_POOL_SIZE=5
# Specify partitioning size for timestamp key-value storage. Allowed values: DAYS, MONTHS, YEARS, INDEFINITE.
export SQL_POSTGRES_TS_KV_PARTITIONING=MONTHS

ThingsBoard team recommends to use Hybrid database approach if you do plan to have 1M+ devices in production or high data ingestion rate (> 5000 msg/sec). In this case, ThingsBoard will be storing timeseries data in Cassandra while continue to use PostgreSQL for main entities (devices/assets/dashboards/customers).

PostgreSQL Installation

Instructions listed below will help you to install PostgreSQL.

# Update your system
sudo yum update

For CentOS 7:

# Install the repository RPM (for CentOS 7):
sudo yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# Install packages
sudo yum -y install epel-release yum-utils
sudo yum-config-manager --enable pgdg12
sudo yum install postgresql12-server postgresql12
# Initialize your PostgreSQL DB
sudo /usr/pgsql-12/bin/postgresql-12-setup initdb
sudo systemctl start postgresql-12
# Optional: Configure PostgreSQL to start on boot
sudo systemctl enable --now postgresql-12

For CentOS 8:

# Install the repository RPM (for CentOS 8):
sudo yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# Install packages
sudo dnf -qy module disable postgresql
sudo dnf -y install postgresql12 postgresql12-server
# Initialize your PostgreSQL DB
sudo /usr/pgsql-12/bin/postgresql-12-setup initdb
sudo systemctl start postgresql-12
# Optional: Configure PostgreSQL to start on boot
sudo systemctl enable --now postgresql-12

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

sudo su - postgres
psql
\password
\q

Then, press “Ctrl+D” to return to main user console.

After configuring the password, edit the pg_hba.conf to use MD5 authentication with the postgres user.

Edit pg_hba.conf file:

sudo nano /var/lib/pgsql/12/data/pg_hba.conf

Locate the following lines:

# IPv4 local connections:
host    all             all             127.0.0.1/32            ident

Replace ident with md5:

host    all             all             127.0.0.1/32            md5

Finally, you should restart the PostgreSQL service to initialize the new configuration:

sudo systemctl restart postgresql-12.service

Connect to the database to create thingsboard DB:

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

Execute create database statement

CREATE DATABASE thingsboard;
\q
Cassandra Installation

Instructions listed below will help you to install Cassandra.

# Add cassandra repository
sudo touch /etc/yum.repos.d/datastax.repo
echo '[datastax]' | sudo tee --append /etc/yum.repos.d/datastax.repo > /dev/null
echo 'name = DataStax Repo for Apache Cassandra' | sudo tee --append /etc/yum.repos.d/datastax.repo > /dev/null
echo 'baseurl = http://rpm.datastax.com/community' | sudo tee --append /etc/yum.repos.d/datastax.repo > /dev/null
echo 'enabled = 1' | sudo tee --append /etc/yum.repos.d/datastax.repo > /dev/null
echo 'gpgcheck = 0' | sudo tee --append /etc/yum.repos.d/datastax.repo > /dev/null

# Cassandra installation
sudo yum install dsc30
# Tools installation
sudo yum install cassandra30-tools
# Start Cassandra
sudo service cassandra start
# Configure the database to start automatically when OS starts.
sudo chkconfig cassandra on
ThingsBoard Configuration

Edit ThingsBoard configuration file

sudo nano /etc/thingsboard/conf/thingsboard.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:

# DB Configuration 
export DATABASE_ENTITIES_TYPE=sql
export DATABASE_TS_TYPE=cassandra
export SPRING_JPA_DATABASE_PLATFORM=org.hibernate.dialect.PostgreSQLDialect
export SPRING_DRIVER_CLASS_NAME=org.postgresql.Driver
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/thingsboard
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=PUT_YOUR_POSTGRESQL_PASSWORD_HERE
export SPRING_DATASOURCE_MAXIMUM_POOL_SIZE=5

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

export CASSANDRA_CLUSTER_NAME=Thingsboard 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=

ThingsBoard team recommends using Timescale database only for companies that already use TimescaleDB in production. In this case, ThingsBoard will be storing timeseries data in TimescaleDB Hypertable while continue to use PostgreSQL for main entities (devices/assets/dashboards/customers).

PostgreSQL Installation

Instructions listed below will help you to install PostgreSQL.

# Update your system
sudo yum update

For CentOS 7:

# Install the repository RPM (for CentOS 7):
sudo yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# Install packages
sudo yum -y install epel-release yum-utils
sudo yum-config-manager --enable pgdg12
sudo yum install postgresql12-server postgresql12
# Initialize your PostgreSQL DB
sudo /usr/pgsql-12/bin/postgresql-12-setup initdb
sudo systemctl start postgresql-12
# Optional: Configure PostgreSQL to start on boot
sudo systemctl enable --now postgresql-12

For CentOS 8:

# Install the repository RPM (for CentOS 8):
sudo yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# Install packages
sudo dnf -qy module disable postgresql
sudo dnf -y install postgresql12 postgresql12-server
# Initialize your PostgreSQL DB
sudo /usr/pgsql-12/bin/postgresql-12-setup initdb
sudo systemctl start postgresql-12
# Optional: Configure PostgreSQL to start on boot
sudo systemctl enable --now postgresql-12

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

sudo su - postgres
psql
\password
\q

Then, press “Ctrl+D” to return to main user console.

After configuring the password, edit the pg_hba.conf to use MD5 authentication with the postgres user.

Edit pg_hba.conf file:

sudo nano /var/lib/pgsql/12/data/pg_hba.conf

Locate the following lines:

# IPv4 local connections:
host    all             all             127.0.0.1/32            ident

Replace ident with md5:

host    all             all             127.0.0.1/32            md5

Finally, you should restart the PostgreSQL service to initialize the new configuration:

sudo systemctl restart postgresql-12.service

Connect to the database to create thingsboard DB:

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

Execute create database statement

CREATE DATABASE thingsboard;
\q
TimescaleDB Installation

Please refer to the official TimescaleDB installation page on RHEL/CentOS distros and follow the instructions in accordance with your installed PostgreSQL version.

ThingsBoard Configuration

Edit ThingsBoard configuration file

sudo nano /etc/thingsboard/conf/thingsboard.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:

# DB Configuration 
export DATABASE_ENTITIES_TYPE=sql
export DATABASE_TS_TYPE=timescale
export SPRING_JPA_DATABASE_PLATFORM=org.hibernate.dialect.PostgreSQLDialect
export SPRING_DRIVER_CLASS_NAME=org.postgresql.Driver
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/thingsboard
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=PUT_YOUR_POSTGRESQL_PASSWORD_HERE
export SPRING_DATASOURCE_MAXIMUM_POOL_SIZE=5
# Specify Interval size for data chunks storage. Please note that this value can be set only once.
export SQL_TIMESCALE_CHUNK_TIME_INTERVAL=604800000 # Number of miliseconds. The current value corresponds to one week.

Step 4. Choose ThingsBoard queue service

ThingsBoard is able to use various messaging systems/brokers for storing the messages and communication between ThingsBoard services. How to choose the right queue implementation?

See corresponding architecture page and rule engine page for more details.

In Memory (built-in and default)
Kafka (recommended for on-prem, production installations)
AWS SQS (managed service from AWS)
Google Pub/Sub (managed service from Google)
Azure Service Bus (managed service from Azure)
RabbitMQ (for small on-prem installations)

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

Kafka Installation

Apache Kafka is an open-source stream-processing software platform.

Install Kafka

We recommend to use Kafka in Docker container, use this instruction for installing.

ThingsBoard Configuration

Edit ThingsBoard configuration file

sudo nano /etc/thingsboard/conf/thingsboard.conf

Add the following line to the configuration file. Don’t forget to replace “localhost:9092” with your real Kafka bootstrap servers:

export TB_QUEUE_TYPE=kafka
export TB_KAFKA_SERVERS=localhost:9092

AWS SQS Configuration

To access AWS SQS service, you first need to create an AWS account.

To work with AWS SQS service you will need to create your next credentials using this instruction:

  • Access key ID
  • Secret access key
ThingsBoard Configuration

Edit ThingsBoard configuration file

sudo nano /etc/thingsboard/conf/thingsboard.conf

Add the following lines to the configuration file. Don’t forget to replace “YOUR_KEY”, “YOUR_SECRET” with your real AWS SQS IAM user credentials and “YOUR_REGION” with your real AWS SQS account region:

export TB_QUEUE_TYPE=aws-sqs
export TB_QUEUE_AWS_SQS_ACCESS_KEY_ID=YOUR_KEY
export TB_QUEUE_AWS_SQS_SECRET_ACCESS_KEY=YOUR_SECRET
export TB_QUEUE_AWS_SQS_REGION=YOUR_REGION

Google Pub/Sub Configuration

To access Pub/Sub service, you first need to create an Google cloud account.

To work with Pub/Sub service you will need to create a project using this instruction.

Create service account credentials with the role “Editor” or “Admin” using this instruction, and save json file with your service account credentials step 9 here.

ThingsBoard Configuration

Edit ThingsBoard configuration file

sudo nano /etc/thingsboard/conf/thingsboard.conf

Add the following lines to the configuration file. Don’t forget to replace “YOUR_PROJECT_ID”, “YOUR_SERVICE_ACCOUNT” with your real Pub/Sub project id, and service account (it is whole data from json file):

export TB_QUEUE_TYPE=pubsub
export TB_QUEUE_PUBSUB_PROJECT_ID=YOUR_PROJECT_ID
export TB_QUEUE_PUBSUB_SERVICE_ACCOUNT=YOUR_SERVICE_ACCOUNT

Azure Service Bus Configuration

To access Azure Service Bus, you first need to create an Azure account.

To work with Service Bus service you will need to create a Service Bus Namespace using this instruction.

Create Shared Access Signature using this instruction.

ThingsBoard Configuration

Edit ThingsBoard configuration file

sudo nano /etc/thingsboard/conf/thingsboard.conf

Add the following lines to the configuration file. Don’t forget to replace “YOUR_NAMESPACE_NAME” with your real Service Bus namespace name, and “YOUR_SAS_KEY_NAME”, “YOUR_SAS_KEY” with your real Service Bus credentials. Note: “YOUR_SAS_KEY_NAME” it is “SAS Policy”, “YOUR_SAS_KEY” it is “SAS Policy Primary Key”:

export TB_QUEUE_TYPE=service-bus
export TB_QUEUE_SERVICE_BUS_NAMESPACE_NAME=YOUR_NAMESPACE_NAME
export TB_QUEUE_SERVICE_BUS_SAS_KEY_NAME=YOUR_SAS_KEY_NAME
export TB_QUEUE_SERVICE_BUS_SAS_KEY=YOUR_SAS_KEY

RabbitMQ Installation

Use this instruction for installing RabbitMQ.

ThingsBoard Configuration

Edit ThingsBoard configuration file

sudo nano /etc/thingsboard/conf/thingsboard.conf

Add the following lines to the configuration file. Don’t forget to replace “YOUR_USERNAME” and “YOUR_PASSWORD” with your real user credentials, “localhost” and “5672” with your real RabbitMQ host and port:

export TB_QUEUE_TYPE=rabbitmq
export TB_QUEUE_RABBIT_MQ_USERNAME=YOUR_USERNAME
export TB_QUEUE_RABBIT_MQ_PASSWORD=YOUR_PASSWORD
export TB_QUEUE_RABBIT_MQ_HOST=localhost
export TB_QUEUE_RABBIT_MQ_PORT=5672

Step 5. [Optional] Memory update for slow machines (1GB of RAM)

Edit ThingsBoard configuration file

sudo nano /etc/thingsboard/conf/thingsboard.conf

Add the following lines to the configuration file.

# Update ThingsBoard memory usage and restrict it to 256MB in /etc/thingsboard/conf/thingsboard.conf
export JAVA_OPTS="$JAVA_OPTS -Xms256M -Xmx256M"

Step 6. Run installation script

Once ThingsBoard service is installed and DB configuration is updated, you can execute the following script:

# --loadDemo option will load demo data: users, devices, assets, rules, widgets.
sudo /usr/share/thingsboard/bin/install/install.sh --loadDemo

Step 7. Start ThingsBoard service

ThingsBoard UI is accessible on 8080 port by default. Make sure that your 8080 port is accessible via firewall. In order to open 8080 port execute the following command:

sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent
sudo firewall-cmd --reload

Execute the following command to start ThingsBoard:

sudo service thingsboard start

Once started, you will be able to open Web UI using the following link:

http://localhost:8080/

The following default credentials are available if you have specified –loadDemo during execution of the installation script:

You can always change passwords for each account in account profile page.

Please allow up to 90 seconds for the Web UI to start. This is applicable only for slow machines with 1-2 CPUs or 1-2 GB RAM.

Post-installation steps

Configure HAProxy to enable HTTPS

You may want to configure HTTPS access using HAProxy. This is possible in case you are hosting ThingsBoard in the cloud and have a valid DNS name assigned to your instance. Please follow this guide to install HAProxy and generate valid SSL certificate using Let’s Encrypt.

Troubleshooting

ThingsBoard logs are stored in the following directory:

/var/log/thingsboard

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

cat /var/log/thingsboard/thingsboard.log | grep ERROR

Next steps