Installing ThingsBoard PE on Ubuntu

Prerequisites
Step 1. Install Java 8 (OpenJDK)
Step 2. ThingsBoard service installation
Step 3. Obtain and configure license key
Step 4. Configure ThingsBoard database
Step 5. Choose ThingsBoard queue service
Step 6. [Optional] Memory update for slow machines (1GB of RAM)
Step 7. Run installation script
Step 8. Start ThingsBoard service
Step 9. Install ThingsBoard WebReport component
Post-installation steps
Troubleshooting
Next steps

Prerequisites

This guide describes how to install ThingsBoard on Ubuntu Server 18.04 LTS. 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.

Step 1. Install Java 8 (OpenJDK)

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

sudo apt update
sudo apt install openjdk-8-jdk

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://dist.thingsboard.io/thingsboard-3.0.1pe.deb

Install ThingsBoard as a service

sudo dpkg -i thingsboard-3.0.1pe.deb

Step 3. Obtain and configure license key

We assume you have already chosen your subscription plan or decided to purchase a perpetual license. If not, please navigate to pricing page to select the best license option for your case and get your license. See How-to get pay-as-you-go subscription or How-to get perpetual license for more details.

Once you get the license secret, you should put it to the thingsboard configuration file. Open the file for editing using the following command:

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

Locate the following configuration block:

# License secret obtained from ThingsBoard License Portal (https://license.thingsboard.io)
# UNCOMMENT NEXT LINE AND PUT YOUR LICENSE SECRET:
# export TB_LICENSE_SECRET=

and put your license secret. Please don’t forget to uncomment the export statement. See example below:

# License secret obtained from ThingsBoard License Portal (https://license.thingsboard.io)
# UNCOMMENT NEXT LINE AND PUT YOUR LICENSE SECRET:
export TB_LICENSE_SECRET=YOUR_LICENSE_SECRET_HERE

Step 4. 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)

PostgreSQL Installation

Instructions listed below will help you to install PostgreSQL.

# install **wget** if not already installed:
sudo apt install -y wget

# import the repository signing key:
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

# add repository contents to your system:
RELEASE=$(lsb_release -cs)
echo "deb http://apt.postgresql.org/pub/repos/apt/ ${RELEASE}"-pgdg main | sudo tee  /etc/apt/sources.list.d/pgdg.list

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

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 and connect to the database to create thingsboard DB:

psql -U postgres -d postgres -h 127.0.0.1 -W
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

PostgreSQL Installation

Instructions listed below will help you to install PostgreSQL.

# install **wget** if not already installed:
sudo apt install -y wget

# import the repository signing key:
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

# add repository contents to your system:
RELEASE=$(lsb_release -cs)
echo "deb http://apt.postgresql.org/pub/repos/apt/ ${RELEASE}"-pgdg main | sudo tee  /etc/apt/sources.list.d/pgdg.list

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

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 and connect to the database to create thingsboard DB:

psql -U postgres -d postgres -h 127.0.0.1 -W
CREATE DATABASE thingsboard;
\q

Cassandra Installation

Instructions listed below will help you to install Cassandra.

# Add cassandra repository
echo 'deb http://www.apache.org/dist/cassandra/debian 311x main' | sudo tee --append /etc/apt/sources.list.d/cassandra.list > /dev/null
curl -L https://www.apache.org/dist/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

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=

PostgreSQL Installation

Instructions listed below will help you to install PostgreSQL.

# install **wget** if not already installed:
sudo apt install -y wget

# import the repository signing key:
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

# add repository contents to your system:
RELEASE=$(lsb_release -cs)
echo "deb http://apt.postgresql.org/pub/repos/apt/ ${RELEASE}"-pgdg main | sudo tee  /etc/apt/sources.list.d/pgdg.list

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

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 and connect to the database to create thingsboard DB:

psql -U postgres -d postgres -h 127.0.0.1 -W
CREATE DATABASE thingsboard;
\q

TimescaleDB Installation

Please refer to the official TimescaleDB installation page on Ubuntu 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 5. 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?

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. It is useful for both on-prem and private cloud deployments. It is also useful if you like to stay independent from your cloud provider. However, some providers also have managed services for Kafka. See AWS MSK for example.
RabbitMQ is recommended if you don’t have much load and you already have experience with this messaging system.
AWS SQS is a fully managed message queuing service from AWS. Useful if you plan to deploy ThingsBoard on AWS.
Google Pub/Sub is a fully managed message queuing service from Google. Useful if you plan to deploy ThingsBoard on Google Cloud.
Azure Service Bus is a fully managed message queuing service from Azure. Useful if you plan to deploy ThingsBoard on Azure.

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

In Memory

Kafka

Kafka (in docker container)

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 ZooKeeper

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

sudo apt-get install zookeeper

Install Kafka

wget http://www-us.apache.org/dist/kafka/2.3.0/kafka_2.12-2.3.0.tgz

tar xzf kafka_2.12-2.3.0.tgz

sudo mv kafka_2.12-2.3.0 /usr/local/kafka

Setup ZooKeeper Systemd Unit file

Create systemd unit file for Zookeeper:

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

Add below contnet:

[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

Setup Kafka Systemd Unit file

Create systemd unit file for Kafka:

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-1.8.0-openjdk-xxx”:

[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

Start ZooKeeper and Kafka:

sudo systemctl start zookeeper

sudo systemctl start kafka

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

Kafka Installation

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

Install Kafka

Use this instruction for installing Kafka in Docker container.

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

For installation RabbitMQ you can use official docs, or our instruction bellow:

Since RabbitMQ is written in Erlang, you need to install Erlang before you can use RabbitMQ:

sudo apt-get install erlang

Install the rabbitmq-server package:

sudo apt-get install rabbitmq-server

Start the Server:

sudo systemctl start rabbitmq-server.service
sudo systemctl enable rabbitmq-server.service

By default, RabbitMQ creates a user named “guest” with a password “guest”. You can also create your own administrator account on RabbitMQ server using following commands. Don’t forget to replace “PUT_YOUR_USER_NAME” like: “admin” and “PUT_YOUR_PASSWORD” with your own user name and password:

sudo rabbitmqctl add_user PUT_YOUR_USER_NAME PUT_YOUR_PASSWORD 
sudo rabbitmqctl set_user_tags PUT_YOUR_USER_NAME administrator
sudo rabbitmqctl set_permissions -p / PUT_YOUR_USER_NAME ".*" ".*" ".*"

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 6. [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 7. 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 8. Start ThingsBoard service

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:

System Administrator: sysadmin@thingsboard.org / sysadmin
Tenant Administrator: tenant@thingsboard.org / tenant
Customer User: customer@thingsboard.org / customer

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

Step 9. Install ThingsBoard WebReport component

Download installation package for the Reports Server component:

wget https://dist.thingsboard.io/tb-web-report-3.0.1pe.deb

Install third-party libraries:

sudo apt install -yq gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 \
     libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 \
     libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 \
     libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 \
     ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils unzip wget

Install Roboto fonts:

sudo apt install fonts-roboto

Install Noto fonts (Japanese, Chinese, etc.):

mkdir ~/noto
cd ~/noto
wget https://noto-website.storage.googleapis.com/pkgs/NotoSansCJKjp-hinted.zip
unzip NotoSansCJKjp-hinted.zip
sudo mkdir -p /usr/share/fonts/noto
sudo cp *.otf /usr/share/fonts/noto
sudo chmod 655 -R /usr/share/fonts/noto/
sudo fc-cache -fv
cd ..
rm -rf ~/noto

Install and start Web Report service:

sudo dpkg -i tb-web-report-3.0.1pe.deb
sudo service tb-web-report start

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

Getting started guides - These guides provide quick overview of main ThingsBoard features. Designed to be completed in 15-30 minutes.
Connect your device - Learn how to connect devices based on your connectivity technology or solution.
Data visualization - These guides contain instructions how to configure complex ThingsBoard dashboards.
Data processing & actions - Learn how to use ThingsBoard Rule Engine.
IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.
Hardware samples - Learn how to connect various hardware platforms to ThingsBoard.
Advanced features - Learn about advanced ThingsBoard features.
Contribution and Development - Learn about contribution and development in ThingsBoard.

Installation

Documentation for installation and configuration of ThingsBoard IoT Platform.

Installing ThingsBoard PE on Ubuntu

Prerequisites

Step 1. Install Java 8 (OpenJDK)

Step 2. ThingsBoard service installation

Step 3. Obtain and configure license key

Step 4. Configure ThingsBoard database

PostgreSQL Installation

ThingsBoard Configuration

PostgreSQL Installation

Cassandra Installation

ThingsBoard Configuration

PostgreSQL Installation

TimescaleDB Installation

ThingsBoard Configuration

Step 5. Choose ThingsBoard queue service

Kafka Installation

Install ZooKeeper

Install Kafka

Setup ZooKeeper Systemd Unit file

Setup Kafka Systemd Unit file

Start ZooKeeper and Kafka:

ThingsBoard Configuration

Kafka Installation

Install Kafka

ThingsBoard Configuration

AWS SQS Configuration

ThingsBoard Configuration

Google Pub/Sub Configuration

ThingsBoard Configuration

Azure Service Bus Configuration

ThingsBoard Configuration

RabbitMQ Installation

ThingsBoard Configuration

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

Step 7. Run installation script

Step 8. Start ThingsBoard service

Step 9. Install ThingsBoard WebReport component

Post-installation steps

Troubleshooting

Next steps