ThingsBoard CE mit Docker installieren: Anleitung Schritt für Schritt

IoT-Plattform souverän und self-hosted aufbauen? WZ-IT plant, installiert und betreibt ThingsBoard auf Ihrer Infrastruktur - Open Source, EU, ohne Cloud-Lock-in. Zur ThingsBoard-Plattform

Sie installieren ThingsBoard CE am schnellsten mit Docker Compose: eine docker-compose.yml mit den Diensten thingsboard/tb-node:4.3.1.2 und postgres:18 anlegen, die Datenbank einmalig initialisieren (docker compose run --rm -e INSTALL_TB=true thingsboard), mit docker compose up -d starten und die Oberfläche unter http://localhost:8080 öffnen. Diese Anleitung führt Schritt für Schritt durch Voraussetzungen, die Compose-Datei, Ports, den ersten Login samt Wechsel der Demo-Passwörter, das erste Device mit Dashboard und die Punkte, die den Sprung in den Produktivbetrieb ausmachen.

Inhaltsverzeichnis

• Voraussetzungen: Hardware und Software
• Welche Datenbank: PostgreSQL oder Cassandra
• Die docker-compose.yml anlegen
• Datenbank initialisieren und Container starten
• Ports und Firewall
• Erster Login und Demo-Passwörter ändern
• Erstes Device und Dashboard anlegen
• Vom Test zum Produktivbetrieb
• Unser Vorgehen bei WZ-IT
• Weiterführende Guides

Voraussetzungen: Hardware und Software

ThingsBoard ist in Java (Spring Boot) geschrieben und braucht eine relationale Datenbank für Entitäten. Für die Software-Seite genügen zwei Komponenten:

• Docker Engine (aktuelle Version) und das Plugin Docker Compose v2 (docker compose, nicht das alte docker-compose).
• Ein Linux-Host ist die übliche Wahl (Ubuntu, Debian, RHEL). macOS und Windows funktionieren mit Docker Desktop für lokale Tests.

Bei der Hardware richtet sich der Bedarf nach Datenbank und Last:

Für den Einstieg empfehlen wir ein PostgreSQL-Setup auf einer VM mit 4 bis 8 GB RAM, etwa auf Proxmox oder einem Hetzner-Server. Was ThingsBoard grundsätzlich leistet, erklärt der Beitrag Was ist ThingsBoard?.

Welche Datenbank: PostgreSQL oder Cassandra

ThingsBoard speichert Entitäten (Geräte, Assets, Dashboards, Relations) immer in PostgreSQL. Für Zeitreihen (Telemetrie) haben Sie die Wahl: PostgreSQL/TimescaleDB oder Cassandra.

• PostgreSQL ist der pragmatische Standard: ein Dienst, ein Backup-Pfad, einfacher Betrieb. Gut bis in den Bereich einiger Tausend Geräte.
• Cassandra oder ein hybrides Setup spielt seine Stärken erst bei sehr hohem Telemetrie-Durchsatz aus (Größenordnung über 5.000 Nachrichten pro Sekunde) oder Millionen von Geräten - um den Preis von mehr RAM und komplexerem Betrieb.

Unsere Empfehlung: mit PostgreSQL starten und erst skalieren, wenn die Messwerte es verlangen. Diese Anleitung nutzt PostgreSQL.

Die docker-compose.yml anlegen

Legen Sie ein Arbeitsverzeichnis an (z. B. ~/thingsboard) und darin folgende docker-compose.yml. Wir verwenden die aktuelle LTS-Linie v4.3 (Stand Juni 2026, Image-Tag 4.3.1.2, siehe thingsboard.io/docs/releases) mit der In-Memory-Queue - ideal für Test und PoC.

services:
  postgres:
    restart: always
    image: "postgres:18"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - tb-postgres-data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d thingsboard"]
      interval: 10s
      timeout: 5s
      retries: 5

  thingsboard:
    restart: always
    image: "thingsboard/tb-node:4.3.1.2"
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "8080:8080"                 # Web-UI + REST-API
      - "1883:1883"                 # MQTT
      - "8883:8883"                 # MQTT mit TLS
      - "5683-5688:5683-5688/udp"   # CoAP + LwM2M
      - "7070:7070"                 # Edge (gRPC)
    environment:
      TB_QUEUE_TYPE: in-memory
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      SPRING_DATASOURCE_USERNAME: postgres
      SPRING_DATASOURCE_PASSWORD: postgres

volumes:
  tb-postgres-data:
    name: tb-postgres-data

Die Passwörter (POSTGRES_PASSWORD, SPRING_DATASOURCE_PASSWORD) gehören in einer echten Installation in eine .env-Datei oder ein Secret, nicht im Klartext ins Compose-File.

Datenbank initialisieren und Container starten

Vor dem ersten Start muss das Datenbankschema einmalig angelegt werden. Aus dem Arbeitsverzeichnis:

# Schema anlegen, optional mit Demo-Daten (Tenant, Device, Dashboard)
docker compose run --rm -e INSTALL_TB=true -e LOAD_DEMO=true thingsboard

Lassen Sie LOAD_DEMO=true weg, wenn Sie eine saubere Installation ohne Demo-Daten möchten. Anschließend die Plattform starten und die Logs verfolgen:

docker compose up -d
docker compose logs -f thingsboard

Sobald in den Logs Started ThingsBoard ... erscheint, ist die Plattform bereit. Öffnen Sie http://localhost:8080 (oder http://SERVER-IP:8080) im Browser.

Ports und Firewall

ThingsBoard exponiert mehrere Ports. Geben Sie nur frei, was Ihre Geräte wirklich brauchen:

MQTT ist in der Praxis das wichtigste Telemetrie-Protokoll; Grundlagen dazu im Beitrag Was ist MQTT?. Wichtig: In Produktion veröffentlichen Sie die Web-UI nicht direkt auf 8080, sondern hinter einem Reverse Proxy (nginx, Traefik, Caddy) mit TLS auf 443. Geräteverbindungen laufen dann über 8883 statt 1883.

Erster Login und Demo-Passwörter ändern

Mit der Demo-Installation sind drei Konten vorhanden:

Melden Sie sich zuerst als System-Administrator an, dann als Tenant-Administrator (mit diesem Konto arbeiten Sie im Alltag). Erster Pflichtschritt: alle Demo-Passwörter ändern. Oben rechts auf das Profilsymbol klicken, Profile, dann Change password. Vergeben Sie für jedes Konto ein starkes, eigenes Passwort - die offizielle Doku warnt ausdrücklich davor, ThingsBoard mit den Default-Zugängen ins Netz zu stellen. Bei einer Clean-Installation ohne LOAD_DEMO existiert nur der System-Administrator; den ersten Tenant legen Sie dann selbst an.

Erstes Device und Dashboard anlegen

Als Tenant-Administrator legen Sie in wenigen Schritten ein Gerät an und sehen erste Daten:

1. Entities → Devices → "+" → Add new device. Namen vergeben (z. B. sensor-01), speichern.
2. Das Device öffnen, Reiter Details, Copy access token - dieser Token authentifiziert das Gerät.
3. Telemetrie senden. Mit dem MQTT-Client mosquitto_pub testen Sie die Verbindung:

mosquitto_pub -d -h localhost -p 1883 \
  -t v1/devices/me/telemetry \
  -u "ACCESS_TOKEN" \
  -m '{"temperature": 21.5, "humidity": 48}'

4. Im Device-Reiter Latest telemetry erscheinen die Werte. Über Add to dashboard oder unter Dashboards → "+" bauen Sie ein erstes Dashboard und ziehen z. B. ein Zeitreihen-Diagramm auf den Telemetrie-Key temperature.

Für umfangreiche Visualisierung oder Reporting koppeln viele Teams ThingsBoard zusätzlich mit Grafana.

Vom Test zum Produktivbetrieb

Das obige Setup ist bewusst schlank. Für den Dauerbetrieb kommen mehrere Punkte hinzu:

• TLS und Reverse Proxy: Web-UI und MQTT nie unverschlüsselt ins Internet. Zertifikate über Let's Encrypt, Terminierung im Reverse Proxy oder direkt in ThingsBoard.
• Backups: PostgreSQL regelmäßig sichern (pg_dump, Volume-Snapshots, Point-in-Time-Recovery). Ohne Backup keine Produktion.
• Queue und Skalierung: Die In-Memory-Queue ist nur für Tests. Produktiv wechseln Sie auf Apache Kafka und bei hoher Last auf ein Microservice-Cluster (Transport-, Core-, Rule-Engine-Services getrennt skaliert).
• Monitoring: Logs, Metriken und Alerting anbinden, Ressourcen (RAM, Disk-I/O) im Blick behalten - Telemetrie-Workloads sind I/O-hungrig.
• Updates: Image-Tag pinnen (nicht latest), vor Upgrades Backup ziehen, Release Notes lesen.

Diese Themen entscheiden über Stabilität und Datenhoheit - und sie sind der Hauptkostentreiber, nicht die Lizenz. Den ehrlichen Kostenvergleich von Community Edition, Professional Edition und Cloud liefert der Beitrag ThingsBoard Preise.

Unser Vorgehen bei WZ-IT

Wir planen, installieren und betreiben ThingsBoard als souveräne, self-hostete IoT-Plattform auf Ihrer Infrastruktur (Proxmox, Hetzner oder On-Premises). Das umfasst Sizing und Datenbankwahl, gehärtete Compose- oder Cluster-Setups mit TLS und Backups, die Anbindung von Geräten und Protokollen, die Modellierung von Device Profiles und Rule Chains sowie Monitoring und Updates. Editionswahl ehrlich an Ihren Anforderungen ausgerichtet, nicht am Lizenzumsatz - im Rahmen unserer ThingsBoard-Expertise und IoT-Plattformentwicklung.

Weiterführende Guides

• ThingsBoard-Expertise - Beratung, Integration und Betrieb
• Was ist ThingsBoard? - Editionen, Architektur und Protokolle
• ThingsBoard Preise - Editionen, Lizenzen und echte Kosten
• Was ist MQTT? - das wichtigste IoT-Protokoll erklärt
• ThingsBoard vs ChirpStack - Anwendungsplattform vs LoRaWAN-Server

Planen Sie eine eigene IoT-Plattform? Lernen Sie uns kennen oder sehen Sie sich unsere IoT-Plattformen an.