Thingsboard Documentation

Documentation for using Thingsboard IoT Platform.

Installing Thingsboard on Linux

IoT PaaS Demo

We recommend to use Thingsboard Live Demo for the seamless experience and the newest features from the latest source code!

Save time on the installation and configuration with several pre-provisioned devices, dashboards available in the cloud and pre-integrated email server to create new customer accounts and users.

This guide describes how to install Thingsboard on a Linux based server machine. Instructions below are provided for Ubuntu 16.04 and CentOS 7. This instructions can be easily adopted to other similar operation systems.

Hardware requirements

To run Thingsboard and third-party components on a single machine you will need at least 1Gb of RAM.

Third-party components installation


Thingsboard service is running on Java 8. Although you are able to start the service using OpenJDK, solution is actively tested on Oracle JDK.

Follow this instructions to install Oracle JDK 8:

Please don’t forget to configure your operation system to use Oracle JDK 8 by default. Corresponding instructions are in the same articles listed above.


Thingsboard service requires Cassandra database. Instructions listed below will help you to install Cassandra.

# Add cassandra repository
echo 'deb 39x main' | sudo tee --append /etc/apt/sources.list.d/cassandra.list > /dev/null
curl | sudo apt-key add -
sudo apt-get update
## Cassandra installation
sudo apt-get install cassandra
## Tools installation
sudo apt-get install cassandra-tools
# 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 =' | 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 service installation

Download installation package or build it from source.


Install thingsboard as a service

sudo dpkg -i thingsboard-1.2.3.deb
sudo rpm -Uvh thingsboard-1.2.3.rpm
Provision database schema and initial data

Once Cassandra and Thingsboard services are installed, you can execute following scripts:

cqlsh -f /usr/share/thingsboard/data/schema.cql
cqlsh -f /usr/share/thingsboard/data/system-data.cql
cqlsh -f /usr/share/thingsboard/data/demo-data.cql
Memory update for slow machines (1GB of RAM)

In case you are running Cassandra and Thingsboard on a single instance that has only 1 GB of RAM memory you need to update memory usage for these services to avoid being killed by OS kernel once services start consuming a lot of memory

For Cassandra service:

# Stop cassandra service
$ sudo service cassandra stop

# Find and set memory options in /etc/cassandra/

# Find and set timeout options in /etc/cassandra/cassandra.yaml
read_request_timeout_in_ms: 20000
range_request_timeout_in_ms: 20000
write_request_timeout_in_ms: 20000
counter_write_request_timeout_in_ms: 50000
cas_contention_timeout_in_ms: 10000
truncate_request_timeout_in_ms: 120000
request_timeout_in_ms: 60000

# Start cassandra service
$ sudo service cassandra start

For Thingsboard service:

# Update Thingsboard memory usage and restrict it to 150MB in /etc/thingsboard/conf/thingsboard.conf
export JAVA_OPTS="$JAVA_OPTS -Xms150M -Xmx150M"

If you are running on a single instance that has 2GB this still can be insufficient for Cassandra under heavy load

In this case if services started to failing please update memory usage accordingly, but with less restrict parameters (for example ‘300M’ instead of ‘150M’)

Start Thingsboard service

Execute following command to start Thingsboard:

sudo service thingsboard start

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


NOTE: Please allow up to 90 seconds for the Web UI to start


Thingsboard logs are stored in the following directory:


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