Install ThingsBoard CE with Docker: Step-by-Step Guide

Build a sovereign, self-hosted IoT platform? WZ-IT designs, installs and runs ThingsBoard on your infrastructure - open source, EU, no cloud lock-in. Explore the ThingsBoard platform

The fastest way to install ThingsBoard CE is with Docker Compose: create a docker-compose.yml with the services thingsboard/tb-node:4.3.1.2 and postgres:18, initialise the database once (docker compose run --rm -e INSTALL_TB=true thingsboard), start it with docker compose up -d and open the UI at http://localhost:8080. This guide walks you step by step through the requirements, the Compose file, ports, the first login including changing the demo passwords, your first device with a dashboard, and what it takes to move into production.

Table of contents

• Requirements: hardware and software
• Which database: PostgreSQL or Cassandra
• Create the docker-compose.yml
• Initialise the database and start the containers
• Ports and firewall
• First login and changing the demo passwords
• Create your first device and dashboard
• From test to production
• How we work at WZ-IT
• Further guides

Requirements: hardware and software

ThingsBoard is written in Java (Spring Boot) and needs a relational database for its entities. On the software side you only need two things:

• Docker Engine (current version) and the Docker Compose v2 plugin (docker compose, not the legacy docker-compose).
• A Linux host is the usual choice (Ubuntu, Debian, RHEL). macOS and Windows work with Docker Desktop for local tests.

Hardware needs depend on the database and load:

For getting started we recommend a PostgreSQL setup on a VM with 4 to 8 GB of RAM, for example on Proxmox or a Hetzner server. For what ThingsBoard does in general, see What is ThingsBoard?.

Which database: PostgreSQL or Cassandra

ThingsBoard always stores entities (devices, assets, dashboards, relations) in PostgreSQL. For time-series data (telemetry) you have a choice: PostgreSQL/TimescaleDB or Cassandra.

• PostgreSQL is the pragmatic default: one service, one backup path, simple operation. Fine up to a few thousand devices.
• Cassandra or a hybrid setup only shows its strengths at very high telemetry throughput (on the order of more than 5,000 messages per second) or millions of devices - at the cost of more RAM and more complex operation.

Our recommendation: start with PostgreSQL and scale only when the numbers demand it. This guide uses PostgreSQL.

Create the docker-compose.yml

Create a working directory (for example ~/thingsboard) and the following docker-compose.yml inside it. We use the current LTS line v4.3 (as of June 2026, image tag 4.3.1.2, see thingsboard.io/docs/releases) with the in-memory queue - ideal for test and 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 over 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

In a real installation the passwords (POSTGRES_PASSWORD, SPRING_DATASOURCE_PASSWORD) belong in a .env file or a secret, not in plain text in the Compose file.

Initialise the database and start the containers

Before the first start the database schema must be created once. From the working directory:

# Create schema, optionally with demo data (tenant, device, dashboard)
docker compose run --rm -e INSTALL_TB=true -e LOAD_DEMO=true thingsboard

Leave out LOAD_DEMO=true if you want a clean install without demo data. Then start the platform and follow the logs:

docker compose up -d
docker compose logs -f thingsboard

Once the logs show Started ThingsBoard ..., the platform is ready. Open http://localhost:8080 (or http://SERVER-IP:8080) in your browser.

Ports and firewall

ThingsBoard exposes several ports. Open only what your devices actually need:

MQTT is the most important telemetry protocol in practice; see What is MQTT? for the basics. Important: in production you do not expose the web UI directly on 8080, but behind a reverse proxy (nginx, Traefik, Caddy) with TLS on 443. Device connections then use 8883 instead of 1883.

First login and changing the demo passwords

A demo install ships with three accounts:

Log in first as the System Administrator, then as the Tenant Administrator (the account you use day to day). First mandatory step: change all demo passwords. Click the profile icon at the top right, choose Profile, then Change password. Set a strong, unique password for each account - the official docs explicitly warn against putting ThingsBoard on a network with the default credentials. On a clean install without LOAD_DEMO only the System Administrator exists; you then create the first tenant yourself.

Create your first device and dashboard

As the Tenant Administrator you can create a device and see live data in a few steps:

1. Entities → Devices → "+" → Add new device. Give it a name (for example sensor-01) and save.
2. Open the device, go to the Details tab and Copy access token - this token authenticates the device.
3. Send telemetry. Test the connection with the MQTT client mosquitto_pub:

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

4. The values appear in the device's Latest telemetry tab. Use Add to dashboard, or go to Dashboards → "+", to build your first dashboard and drop, for example, a time-series chart onto the temperature telemetry key.

For richer visualisation or reporting, many teams pair ThingsBoard with Grafana.

From test to production

The setup above is deliberately lean. For continuous operation several points come on top:

• TLS and reverse proxy: never expose the web UI or MQTT unencrypted to the internet. Use Let's Encrypt certificates, terminating TLS in the reverse proxy or directly in ThingsBoard.
• Backups: back up PostgreSQL regularly (pg_dump, volume snapshots, point-in-time recovery). No backup, no production.
• Queue and scaling: the in-memory queue is for testing only. In production switch to Apache Kafka and, under high load, to a microservice cluster (transport, core and rule-engine services scaled separately).
• Monitoring: wire up logs, metrics and alerting, and keep an eye on resources (RAM, disk I/O) - telemetry workloads are I/O hungry.
• Updates: pin the image tag (not latest), take a backup before upgrades, read the release notes.

These topics decide stability and data sovereignty - and they are the main cost driver, not the license. For an honest cost comparison of the Community Edition, Professional Edition and Cloud, see ThingsBoard pricing.

How we work at WZ-IT

We design, install and run ThingsBoard as a sovereign, self-hosted IoT platform on your infrastructure (Proxmox, Hetzner or on-premises). That covers sizing and database choice, hardened Compose or cluster setups with TLS and backups, connecting devices and protocols, modelling device profiles and rule chains, plus monitoring and updates. Edition choice is aligned honestly with your requirements, not with license revenue - as part of our ThingsBoard expertise and IoT platform development.

Further guides

• ThingsBoard expertise - consulting, integration and operations
• What is ThingsBoard? - editions, architecture and protocols
• ThingsBoard pricing - editions, licenses and real costs
• What is MQTT? - the most important IoT protocol explained
• ThingsBoard vs ChirpStack - application platform vs LoRaWAN server

Planning your own IoT platform? Get to know us or take a look at our IoT platforms.