ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform.
Open documentation for releases before 1.3

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. These instructions can be easily adapted to other similar operating 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, the solution is actively tested on Oracle JDK.

Follow this instructions to install Oracle JDK 8:

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

[Optional] External database installation

ThingsBoard is able to use SQL or NoSQL(Cassandra) database layer. By default, ThingsBoard uses embedded HSQLDB instance which is very convenient for evaluation or development purposes.

If this is your first experience with ThingsBoard we recommend to skip this step and use the embedded database.
Alternatively, you can configure your platform to use either scalable Cassandra DB cluster or various SQL databases. If you prefer to use an SQL database, we recommend PostgreSQL.

SQL Database: PostgreSQL

NOTE: This is an optional step. It is required only for production usage. You can use embedded HSQLDB for platform evaluation or development

Instructions listed below will help you to install PostgreSQL.

resources/postgresql-ubuntu-installation.sh
sudo apt-get update
sudo apt-get install postgresql postgresql-contrib
sudo service postgresql start
resources/postgresql-centos-installation.sh
# Update your system
sudo yum update
# Install packages
sudo yum install postgresql-server postgresql-contrib
# Initialize your PostgreSQL DB
sudo postgresql-setup initdb
sudo systemctl start postgresql
# Optional: Configure PostgreSQL to start on boot
sudo systemctl enable postgresql

Once PostgreSQL is installed you may want to create a new user or set the password for the the main user.

See the following guides for more details: using postgresql roles and databases and changing the postgres user password

When it’s done, connect to the database and create thingsboard DB:

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

CREATE DATABASE thingsboard;
\q
NoSQL Database: Cassandra

NOTE: This is an optional step. It is required only for production usage. You can use embedded HSQLDB for platform evaluation or development

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.3.1/thingsboard-1.3.1.deb
resources/thingsboard-centos-download.sh
wget https://github.com/thingsboard/thingsboard/releases/download/v1.3.1/thingsboard-1.3.1.rpm

Install ThingsBoard as a service

resources/thingsboard-ubuntu-installation.sh
sudo dpkg -i thingsboard-1.3.1.deb
resources/thingsboard-centos-installation.sh
sudo rpm -Uvh thingsboard-1.3.1.rpm

[Optional] Configure ThingsBoard to use the external database

NOTE: This is an optional step. It is required only for production usage. You can use embedded HSQLDB for platform evaluation or development

Edit ThingsBoard configuration file

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

Comment ‘# HSQLDB DAO Configuration’ block.

# HSQLDB DAO Configuration
#spring:
#  data:
#    jpa:
#      repositories:
#        enabled: "true"
#  jpa:
#    hibernate:
#      ddl-auto: "validate"
#    database-platform: "org.hibernate.dialect.HSQLDialect"
#  datasource:
#    driverClassName: "${SPRING_DRIVER_CLASS_NAME:org.hsqldb.jdbc.JDBCDriver}"
#    url: "${SPRING_DATASOURCE_URL:jdbc:hsqldb:file:${SQL_DATA_FOLDER:/tmp}/thingsboardDb;sql.enforce_size=false}"
#    username: "${SPRING_DATASOURCE_USERNAME:sa}"
#    password: "${SPRING_DATASOURCE_PASSWORD:}"

For PostgreSQL:

Uncomment ‘# PostgreSQL DAO Configuration’ block.

# PostgreSQL DAO Configuration
spring:
  data:
    jpa:
      repositories:
        enabled: "true"
  jpa:
    hibernate:
      ddl-auto: "validate"
    database-platform: "org.hibernate.dialect.PostgreSQLDialect"
  datasource:
    driverClassName: "${SPRING_DRIVER_CLASS_NAME:org.postgresql.Driver}"
    url: "${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/thingsboard}"
    username: "${SPRING_DATASOURCE_USERNAME:postgres}"
    password: "${SPRING_DATASOURCE_PASSWORD:postgres}"

For Cassandra DB:

Locate and set database type configuration parameter to ‘cassandra’.

database:
  type: "${DATABASE_TYPE:cassandra}" # cassandra OR sql

Memory update for slow machines (1GB of RAM)

We recommend to use embedded HSQLDB or PostgreSQL DB in this setup. We don’t recommend to use Cassandra on machines with less then 4GB of RAM.

For ThingsBoard service:

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

Run installation script

Once ThingsBoard service is installed, 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

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/

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