# ThingsBoard IoT Platform

> Open-source IoT platform for device management, data collection, and visualization.

- Category: Home Lab & Self-Hosting
- Difficulty: advanced
- Components: thingsboard, postgresql, redis, mqtt
- Tags: thingsboard, iot, mqtt, device-management, telemetry
- Source: https://docker.recipes/homelab/thingsboard-iot

## Overview

ThingsBoard is an open-source IoT platform developed to simplify the collection, processing, and visualization of telemetry data from connected devices. Originally created in 2016 by the ThingsBoard team, it has evolved into a comprehensive solution that handles device management, data collection, rule processing, and dashboard creation for IoT deployments ranging from small prototypes to enterprise-scale implementations. The platform supports multiple communication protocols including MQTT, CoAP, HTTP, and LWM2M, making it versatile for diverse IoT ecosystems. This stack combines ThingsBoard with PostgreSQL as the primary database for storing device data and metadata, Redis for caching and session management to improve response times, and Eclipse Mosquitto as an external MQTT broker for device communication. PostgreSQL provides the robust data integrity and complex querying capabilities needed for time-series telemetry data and device relationships, while Redis accelerates frequent operations like dashboard loading and real-time data access. The inclusion of Mosquitto as a separate MQTT broker allows for more granular control over device connectivity and can handle high-frequency telemetry ingestion independently of the main ThingsBoard container. This configuration is ideal for IoT developers, system integrators, and organizations looking to deploy a complete device management platform without the complexity of cloud vendor lock-in. The stack provides everything needed to onboard devices, create data visualization dashboards, set up alerting rules, and manage device firmware updates, making it particularly valuable for industrial IoT applications, smart building management, and environmental monitoring systems where data sovereignty and customization are priorities.

## Features

- Multi-protocol device connectivity supporting MQTT, CoAP, HTTP, and LWM2M for diverse IoT device ecosystems
- Advanced rule engine with visual flow-based programming for processing telemetry data and triggering actions
- Time-series data storage in PostgreSQL optimized for high-frequency sensor data ingestion and historical analysis
- Real-time dashboard builder with customizable widgets for gauges, charts, maps, and device controls
- Device provisioning and management with support for device profiles, credentials, and over-the-air updates
- Redis-accelerated data access for sub-second dashboard loading and real-time telemetry visualization
- Built-in alarm system with configurable thresholds, severity levels, and notification channels
- Multi-tenancy support with customer hierarchy, user roles, and resource isolation for managed IoT services

## Use cases

- Industrial IoT monitoring for manufacturing equipment with predictive maintenance alerts and production dashboards
- Smart building automation managing HVAC, lighting, and security sensors with centralized control interfaces
- Environmental monitoring networks collecting air quality, weather, and pollution data across multiple locations
- Fleet management systems tracking vehicle telemetry, GPS coordinates, and maintenance schedules
- Agricultural IoT deployments monitoring soil moisture, temperature, and irrigation systems for precision farming
- Energy management platforms collecting data from smart meters, solar panels, and battery storage systems
- Home automation labs integrating various smart devices with custom dashboards and automation rules

## Prerequisites

- Minimum 4GB RAM recommended for ThingsBoard with PostgreSQL time-series data and concurrent device connections
- Available ports 8080 (web interface), 1883/1884 (MQTT), 7070 (RPC), and 5683-5688 (CoAP/UDP)
- Basic understanding of MQTT protocol and IoT device communication patterns
- Familiarity with time-series data concepts and PostgreSQL for advanced rule engine configuration
- Knowledge of JSON message formats for device telemetry and attribute payloads
- Understanding of SSL/TLS certificates if planning to secure MQTT and web interface communications

## docker-compose.yml

```yaml
services:
  thingsboard:
    image: thingsboard/tb-postgres:latest
    ports:
      - "8080:9090"
      - "1883:1883"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    environment:
      TB_QUEUE_TYPE: in-memory
    volumes:
      - thingsboard_data:/data
      - thingsboard_logs:/var/log/thingsboard
    networks:
      - tb-net
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: thingsboard
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - tb-net
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - tb-net
    restart: unless-stopped

  mosquitto:
    image: eclipse-mosquitto:latest
    ports:
      - "1884:1883"
      - "9001:9001"
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
      - mosquitto_data:/mosquitto/data
      - mosquitto_log:/mosquitto/log
    networks:
      - tb-net
    restart: unless-stopped

volumes:
  thingsboard_data:
  thingsboard_logs:
  postgres_data:
  redis_data:
  mosquitto_data:
  mosquitto_log:

networks:
  tb-net:
    driver: bridge
```

## .env

```bash
# PostgreSQL
POSTGRES_USER=thingsboard
POSTGRES_PASSWORD=secure_postgres_password
```

## Usage notes

- ThingsBoard at http://localhost:8080
- Default login: tenant@thingsboard.org / tenant
- MQTT broker at localhost:1883
- CoAP at localhost:5683

## Troubleshooting

- ThingsBoard fails to start with database connection errors: Ensure PostgreSQL container is fully initialized before ThingsBoard starts, add depends_on with health checks
- Devices cannot connect via MQTT with authentication failures: Verify device credentials in ThingsBoard device management and check MQTT broker logs for connection attempts
- Dashboard widgets show 'No data' despite device connectivity: Check device telemetry keys match widget data key configuration and verify time range settings
- High memory usage and slow dashboard loading: Increase Redis memory allocation and enable ThingsBoard caching configuration in environment variables
- Rule engine chains not triggering properly: Verify rule node connections and check ThingsBoard logs for rule processing errors and message flow debugging
- CoAP devices timing out during communication: Ensure UDP port range 5683-5688 is properly exposed and check firewall settings for UDP traffic

