Deploying ThingsBoard

Introduction

ThingsBoard is a powerful open-source IoT platform for device management, data collection, processing, and visualization. It enables you to connect devices, collect and store telemetry data, create real-time dashboards, and set up automated rules for device control and notifications. ThingsBoard supports millions of devices and provides enterprise-grade features for building complete IoT solutions.

Key features of ThingsBoard include:

• Device Management: Provision and manage IoT devices with credentials and metadata
• Multi-Protocol Support: MQTT, CoAP, HTTP, and LwM2M connectivity
• Real-Time Dashboards: Create interactive visualizations with drag-and-drop widgets
• Rule Engine: Process telemetry data and trigger actions based on conditions
• Alarm System: Configure thresholds and receive alerts via email, SMS, or webhooks
• Multi-Tenancy: Isolated environments for different customers or departments
• REST API: Comprehensive API for integration with external systems
• Edge Computing: Process data locally with ThingsBoard Edge
• White-Labeling: Customize branding for your IoT platform
• Asset Management: Model complex IoT hierarchies and relationships

This guide walks you through deploying ThingsBoard on Klutch.sh, setting up the database, and connecting your first IoT devices.

Why Deploy ThingsBoard on Klutch.sh

Deploying ThingsBoard on Klutch.sh provides several advantages for IoT applications:

Always-On Platform: IoT devices require constant connectivity. Klutch.sh ensures your platform remains available 24/7 for device connections and data collection.

Simplified Deployment: Klutch.sh handles container orchestration, letting you focus on your IoT solution rather than infrastructure management.

Scalable Resources: Start small and scale resources as your device fleet grows and data volumes increase.

Persistent Storage: Reliable storage for device data, dashboards, and configurations across deployments.

HTTPS by Default: Secure web interface access with automatic SSL certificates.

GitHub Integration: Version control your configuration and enable automatic redeployments.

Prerequisites

Before deploying ThingsBoard on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and IoT concepts
• PostgreSQL database (can be deployed on Klutch.sh)
• IoT devices to connect (or simulators for testing)

Understanding ThingsBoard Architecture

ThingsBoard consists of several key components:

Core Application: Java-based server handling device connectivity, data processing, and REST API.

Rule Engine: Processes incoming telemetry and executes actions based on configured rules.

Database Layer: PostgreSQL for entities and configuration; optional Cassandra/TimescaleDB for time-series data.

Transport Layer: Handles device connectivity via MQTT, HTTP, CoAP, and LwM2M.

Web UI: Angular-based dashboard for device management and visualization.

Preparing Your Repository

Create a GitHub repository with the following structure:

thingsboard-deploy/
├── Dockerfile
├── .dockerignore
└── config/
    └── thingsboard.yml

Creating the Dockerfile

FROM thingsboard/tb-postgres:latest

# Environment configuration
ENV TB_QUEUE_TYPE=in-memory
ENV SPRING_DATASOURCE_URL=jdbc:postgresql://${DATABASE_HOST}:5432/${DATABASE_NAME}
ENV SPRING_DATASOURCE_USERNAME=${DATABASE_USER}
ENV SPRING_DATASOURCE_PASSWORD=${DATABASE_PASSWORD}

# JWT configuration
ENV JWT_TOKEN_SIGNING_KEY=${JWT_TOKEN_SIGNING_KEY}

# HTTP transport configuration
ENV HTTP_BIND_ADDRESS=0.0.0.0
ENV HTTP_BIND_PORT=8080

# MQTT transport configuration
ENV MQTT_BIND_ADDRESS=0.0.0.0
ENV MQTT_BIND_PORT=1883

# Expose ports
EXPOSE 8080 1883 5683/udp

# The base image includes the default entrypoint

Environment Variables Reference

Variable	Required	Default	Description
DATABASE_HOST	Yes	-	PostgreSQL hostname
DATABASE_NAME	Yes	thingsboard	PostgreSQL database name
DATABASE_USER	Yes	-	PostgreSQL username
DATABASE_PASSWORD	Yes	-	PostgreSQL password
JWT_TOKEN_SIGNING_KEY	Yes	-	Secret key for JWT tokens
TB_QUEUE_TYPE	No	in-memory	Message queue type
MQTT_BIND_PORT	No	1883	MQTT broker port

Deploying on Klutch.sh

Set Up PostgreSQL Database

ThingsBoard requires PostgreSQL. Deploy it as a separate app on Klutch.sh:

Mount Path	Size	Purpose
/var/lib/postgresql/data	50 GB	Database storage for IoT data

Initialize the database with:

• Database name: thingsboard
• User with full permissions

Generate JWT Signing Key

Create a secure key for JWT token signing:

openssl rand -base64 32

Save this key for the environment variables.

Push Your Repository to GitHub

Commit and push your Dockerfile and configuration.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “thingsboard” or “iot-platform”.

Create the ThingsBoard App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set the traffic type to HTTP with the internal port set to 8080.

Set Environment Variables

Configure the required environment variables:

Variable	Value
DATABASE_HOST	Your PostgreSQL host
DATABASE_NAME	thingsboard
DATABASE_USER	Your database user
DATABASE_PASSWORD	Your secure password
JWT_TOKEN_SIGNING_KEY	Your generated key

Attach Persistent Volumes

Add persistent storage:

Mount Path	Size	Purpose
/data	10 GB	ThingsBoard data and logs

Deploy Your Application

Click Deploy to build and launch ThingsBoard.

Access the Platform

Once deployed, access ThingsBoard at https://your-app-name.klutch.sh.

Default credentials:

• Sysadmin: sysadmin@thingsboard.org / sysadmin
• Tenant Admin: tenant@thingsboard.org / tenant

Initial Configuration

First-Time Setup

1. Log in as the system administrator
2. Change default passwords immediately
3. Configure system settings
4. Create your tenant and users

Creating Tenants

Tenants are isolated environments:

1. Navigate to Tenants
2. Click Add Tenant
3. Configure tenant details
4. Create a tenant administrator

Setting Up Users

Create users for your organization:

• Tenant Administrators: Full tenant access
• Customer Users: Limited access to assigned devices and dashboards

Device Management

Adding Devices

Create devices in ThingsBoard:

1. Navigate to Devices
2. Click Add Device
3. Enter device name and type
4. Copy access credentials for device configuration

Device Credentials

ThingsBoard supports multiple authentication methods:

Method	Description
Access Token	Simple token-based authentication
X.509 Certificate	Certificate-based mutual TLS
MQTT Basic Credentials	Username/password for MQTT

Connecting Devices

Connect devices using MQTT, HTTP, or CoAP:

MQTT Connection Example:

• Host: your-app-name.klutch.sh
• Port: 1883 (or 8883 for TLS)
• Username: Device access token
• Topic: v1/devices/me/telemetry

HTTP API Example:

POST https://your-app-name.klutch.sh/api/v1/{accessToken}/telemetry
Content-Type: application/json

{"temperature": 25.5, "humidity": 60}

Dashboard Creation

Building Dashboards

Create visualizations for your IoT data:

1. Navigate to Dashboards
2. Click Add Dashboard
3. Enter dashboard name
4. Open the dashboard editor

Adding Widgets

ThingsBoard provides numerous widget types:

• Charts: Line, bar, pie, and other chart types
• Gauges: Display current values
• Maps: Geographic visualization
• Cards: Display entity attributes
• Control Widgets: Buttons, switches, sliders

Configuring Data Sources

Connect widgets to device data:

1. Add a widget to the dashboard
2. Configure the data source (device, entity alias)
3. Select telemetry keys to display
4. Customize appearance

Rule Engine

Understanding Rules

The rule engine processes incoming data:

1. Message Types: Telemetry, attributes, events
2. Rule Nodes: Processing logic elements
3. Rule Chains: Connected sequences of nodes
4. Actions: Outputs and integrations

Creating Rule Chains

Build automated workflows:

1. Navigate to Rule Chains
2. Create or modify a rule chain
3. Add nodes for processing
4. Connect nodes to define flow
5. Save and activate

Common Rule Patterns

• Threshold Alarms: Alert when values exceed limits
• Data Enrichment: Add metadata to telemetry
• External Integration: Send data to external systems
• Device Control: Trigger RPC commands

Production Best Practices

Security Recommendations

• Change Default Passwords: Immediately update all default credentials
• Enable HTTPS: Use Klutch.sh’s automatic SSL for web interface
• Secure MQTT: Consider TLS for MQTT connections
• Access Control: Use proper roles and permissions
• JWT Security: Use strong signing keys

Performance Optimization

• Database Tuning: Optimize PostgreSQL for time-series workloads
• Queue Configuration: Consider Kafka/RabbitMQ for high-volume deployments
• Resource Allocation: Allocate adequate memory for JVM
• Data Retention: Configure TTL for telemetry data

Scaling Considerations

For large deployments:

• Use TimescaleDB or Cassandra for time-series data
• Deploy multiple ThingsBoard nodes
• Use external message queue (Kafka)
• Consider ThingsBoard Edge for local processing

Troubleshooting

Devices Not Connecting

• Verify device credentials
• Check network connectivity
• Review transport logs
• Ensure correct protocol and port

Dashboard Not Updating

• Verify device is sending telemetry
• Check WebSocket connection
• Review rule chain processing
• Confirm data source configuration

High Memory Usage

• Increase JVM heap size
• Configure data retention policies
• Optimize rule chains
• Review dashboard complexity

Database Performance Issues

• Check PostgreSQL configuration
• Add appropriate indexes
• Configure connection pooling
• Consider time-series extensions

Additional Resources

• ThingsBoard Documentation
• ThingsBoard GitHub Repository
• ThingsBoard Sample Projects
• ThingsBoard REST API
• ThingsBoard YouTube Channel
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying ThingsBoard on Klutch.sh provides a robust foundation for building IoT applications. With comprehensive device management, real-time dashboards, and powerful rule engine capabilities, ThingsBoard can handle everything from simple sensor networks to complex industrial IoT deployments. The combination of ThingsBoard’s feature-rich platform and Klutch.sh’s reliable infrastructure ensures your IoT solution remains operational and scalable as your device fleet grows.