Thingsboard Documentation

Documentation for using Thingsboard IoT Platform.

Installing Thingsboard on Linux

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

Java

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.

Cassandra

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

resources/cassandra-ubuntu-installation.sh
# Add cassandra repository
echo 'deb http://www.apache.org/dist/cassandra/debian 39x main' | sudo tee --append /etc/apt/sources.list.d/cassandra.list > /dev/null
curl 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
resources/cassandra-centos-installation.sh
# 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 service installation

Download installation package or build it from source.

resources/thingsboard-ubuntu-download.sh
wget https://github.com/thingsboard/thingsboard/releases/download/v1.2.1/thingsboard-1.2.1.deb
resources/thingsboard-centos-download.sh
wget https://github.com/thingsboard/thingsboard/releases/download/v1.2.1/thingsboard-1.2.1.rpm

Install thingsboard as a service

resources/thingsboard-ubuntu-installation.sh
sudo dpkg -i thingsboard-1.2.1.deb
resources/thingsboard-centos-installation.sh
sudo rpm -Uvh thingsboard-1.2.1.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/cassandra-env.sh
MAX_HEAP_SIZE="150M"
HEAP_NEWSIZE="50M"

# 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:

http://localhost:8080/

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

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