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

Installation

Documentation for installation and configuration of ThingsBoard IoT Platform.

ThingsBoard Professional Edition using Docker with Cassandra (Linux or Mac OS)

This guide will help you to setup ThingsBoard in Docker with Cassandra DB. For this purpose, we will use docker container images available on Docker Hub.

Prerequisites

Before starting please make sure Docker CE and Docker Compose are installed in your system.

Step 1. Checkout ThingsBoard PE Node Image

Please checkout ThingsBoard PE Node Image from Docker Hub. You will need to open all verified images and click on “Proceed to checkout” to accept ThingsBoard PE license agreement.

Listing image mandatory for checkout for your convenience below:

image

Populate basic information about yourself and click “Get Content”

image

Step 2. Pull ThingsBoard PE Image

Make sure your have logged in to docker hub using command line.

docker pull store/thingsboard/tb-pe-node:3.0.1PE

Step 3. Clone ThingsBoard PE Docker Compose scripts

git clone https://github.com/thingsboard/thingsboard-pe-docker-compose.git tb-pe-docker-compose
cd tb-pe-docker-compose
git checkout develop/cassandra-standalone

Step 4. Obtain your 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. We will reference the license key you have obtained during this step as PUT_YOUR_LICENSE_SECRET_HERE later in this guide.

Step 5. Configure your license key

nano tb-node.env

and put the license secret parameter

# ThingsBoard server configuration

HTTP_LOG_CONTROLLER_ERROR_STACK_TRACE=false

TB_LICENSE_SECRET=PUT_YOUR_LICENSE_SECRET_HERE

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

ThingsBoard includes In Memory Queue service and use it by default without extra settings.

nano tb-node.env

Add the following line to the file.

TB_QUEUE_TYPE=in-memory

Check docker-compose.yml and configure ports if you need:

nano docker-compose.yml

services:
  tbpe:
    restart: always
    image: "${DOCKER_REPO}/${TB_NODE_DOCKER_NAME}:${TB_VERSION}"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683:5683"

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

Configuration environment file for ThingsBoard queue service:

nano tb-node.env

Add the following line to the file.

TB_QUEUE_TYPE=kafka
TB_KAFKA_SERVERS=kafka:9092

Check docker-compose.yml and configure ports if you need:

services:
  zookeeper:
    restart: always
    image: "zookeeper:3.5"
    ports:
      - "2181:2181"
    environment:
      ZOO_MY_ID: 1
      ZOO_SERVERS: server.1=zookeeper:2888:3888;zookeeper:2181
  kafka:
    restart: always
    image: wurstmeister/kafka
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_LISTENERS: INSIDE://:9093,OUTSIDE://:9092
      KAFKA_ADVERTISED_LISTENERS: INSIDE://:9093,OUTSIDE://kafka:9092
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INSIDE:PLAINTEXT,OUTSIDE:PLAINTEXT
      KAFKA_INTER_BROKER_LISTENER_NAME: INSIDE
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
  tbpe:
    restart: always
    image: "${DOCKER_REPO}/${TB_NODE_DOCKER_NAME}:${TB_VERSION}"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683:5683"
    depends_on:
      - kafka

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

Create docker compose file for ThingsBoard queue service:

sudo nano docker-compose.yml

Add the following line to the yml 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, and “PUT_YOUR_LICENSE_SECRET_HERE” with your license secret obtained on the first step:

version: '2.2'
services:
  mytbpe:
    restart: always
    image: "store/thingsboard/tb-pe:3.0.1PE"
    ports:
      - "8080:9090"
      - "1883:1883"
      - "5683:5683/udp"
    environment:
      TB_QUEUE_TYPE: aws-sqs
      TB_QUEUE_AWS_SQS_ACCESS_KEY_ID: YOUR_KEY
      TB_QUEUE_AWS_SQS_SECRET_ACCESS_KEY: YOUR_SECRET
      TB_QUEUE_AWS_SQS_REGION: YOUR_REGION
      TB_LICENSE_SECRET: PUT_YOUR_LICENSE_SECRET_HERE
      TB_LICENSE_INSTANCE_DATA_FILE: /data/license.data
    volumes:
      - ~/.mytbpe-data:/data
      - ~/.mytbpe-logs:/var/log/thingsboard

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.

nano tb-node.env

Add the following line to the yml 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):

TB_QUEUE_TYPE=pubsub
TB_QUEUE_PUBSUB_PROJECT_ID=YOUR_PROJECT_ID
TB_QUEUE_PUBSUB_SERVICE_ACCOUNT=YOUR_SERVICE_ACCOUNT

Check docker-compose.yml and configure ports if you need:

nano docker-compose.yml

services:
  tbpe:
    restart: always
    image: "${DOCKER_REPO}/${TB_NODE_DOCKER_NAME}:${TB_VERSION}"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683:5683"

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.

nano tb-node.env

Add the following line to the 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”:

TB_QUEUE_TYPE: service-bus
TB_QUEUE_SERVICE_BUS_NAMESPACE_NAME: YOUR_NAMESPACE_NAME
TB_QUEUE_SERVICE_BUS_SAS_KEY_NAME: YOUR_SAS_KEY_NAME
TB_QUEUE_SERVICE_BUS_SAS_KEY: YOUR_SAS_KEY

Check docker-compose.yml and configure ports if you need:

nano docker-compose.yml

services:
  tbpe:
    restart: always
    image: "${DOCKER_REPO}/${TB_NODE_DOCKER_NAME}:${TB_VERSION}"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683:5683"

For installing RabbitMQ use this instruction.

Configuration environment file for ThingsBoard queue service:

nano tb-node.env

Add the following line to the 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:

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

Check docker-compose.yml and configure ports if you need:

nano docker-compose.yml

services:
  tbpe:
    restart: always
    image: "${DOCKER_REPO}/${TB_NODE_DOCKER_NAME}:${TB_VERSION}"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683:5683"

Step 7. Installation

Execute installation script

$ ./docker-install-tb.sh --loadDemo

Where:

Step 8. Running

Execute the following command to start services:

$ ./docker-start-services.sh

After a while when all services will be successfully started you can open http://{your-host-ip}:9090 in you browser (for ex. http://localhost:9090). You should see ThingsBoard login page.

Use the following default credentials:

If you installed DataBase with demo data (using --loadDemo flag) you can also use the following credentials:

In case of any issues you can examine service logs for errors. For example to see ThingsBoard node logs execute the following command:

$ docker-compose logs -f tbpe

Or use docker-compose ps to see the state of all the containers. Use docker-compose logs --f to inspect the logs of all running services. See docker-compose logs command reference for details.

Execute the following command to stop services:

$ ./docker-stop-services.sh

Execute the following command to stop and completely remove deployed docker containers:

$ ./docker-remove-services.sh

Execute the following command to update particular or all services (pull newer docker image and rebuild container):

$ ./docker-update-service.sh

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.

Upgrading

In case when database upgrade is needed, execute the following commands:

$ ./docker-stop-services.sh
$ ./docker-upgrade-tb.sh --fromVersion=[FROM_VERSION]
$ ./docker-start-services.sh

Where:

Next steps