ThingsBoard is an open-source IoT platform that bundles device management, dashboards, alerting and a visual rule engine into one product, instead of you assembling MQTT, Node-RED and Grafana separately. The Community Edition is free and self-hostable on your own VPS, needing at least 4GB of RAM (8GB recommended), with the official Docker deployment being the simplest path to a working install.
The problem this solves
Building an IoT dashboard from individual pieces, an MQTT broker, Node-RED for logic, Grafana for visualisation, works well and is covered elsewhere on this site, but it’s genuinely several separate things to install, secure and keep working together. ThingsBoard takes a different approach: one platform that already includes device management, a rule engine, dashboards, and multi-tenant user permissions, all talking to each other natively because they were built as one product rather than wired together afterward.
The trade-off is real and worth naming honestly: ThingsBoard is less flexible than a hand-built stack for genuinely unusual requirements, and it’s a heavier piece of software to run. For most projects past the hobbyist stage, especially anything involving multiple customers, sites, or device types, that trade-off favours ThingsBoard.
How it fits together
Sizing requirements
| Deployment | RAM | Notes |
|---|---|---|
| Single instance (Docker, PostgreSQL) | 4GB minimum, 8GB recommended | Suitable for development, evaluation, and most small-to-medium production deployments |
| Cluster (multiple nodes, Kafka) | 8GB+ per node, 16GB recommended for production | Only needed once you’ve genuinely outgrown a single instance |
Most projects on this site fit comfortably in the single-instance row. ThingsBoard’s own documentation is explicit that the built-in in-memory message queue is fine for development and proof-of-concept work, but not recommended for production or any multi-node setup, where Kafka becomes the recommended option.
Installing via Docker
Create a dedicated directory and pull the official image:
mkdir ~/thingsboard && cd ~/thingsboard
docker run -it -d --name tb -p 8080:8080 -p 1883:1883 -p 7070:7070
-p 5683-5688:5683-5688/udp
-v ~/.mytb-data:/data
-v ~/.mytb-logs:/var/log/thingsboard
--restart always
thingsboard/tb-postgresThen initialise the database schema and load the default system resources:
docker exec -it tb bash -c "/usr/share/thingsboard/bin/install/install.sh"Once that completes, the platform is reachable at http://your-server-ip:8080. Log in with the default system administrator account, then change the password immediately, before doing anything else, since the default credentials are publicly documented in ThingsBoard’s own setup guides.
Ports, and what to actually expose
| Port | Purpose | Expose publicly? |
|---|---|---|
| 8080 | Web UI / HTTP API | Yes, ideally behind HTTPS via a reverse proxy |
| 1883 | MQTT device connections | Yes, this is how devices report data in |
| 5683-5688/udp | CoAP and LwM2M device connections | Only if you have devices using these protocols |
| 7070 | RPC, used for Edge instance sync | Only if you’re running a ThingsBoard Edge deployment alongside it |
Apply the same firewall discipline as the rest of this site: open exactly what your actual devices need, nothing left open speculatively. See VPS Security Hardening Checklist for the baseline server hardening that applies regardless of what’s running on top.
HTTPS via reverse proxy
The same Nginx + Let’s Encrypt pattern used elsewhere on this site applies directly here: terminate HTTPS at Nginx, proxy through to ThingsBoard’s port 8080 internally, and close 8080 to direct external access once that’s working.
Your first rule chain
ThingsBoard’s rule engine is the part that takes it beyond “just a dashboard”. A rule chain is a visual flow, similar in spirit to Node-RED, that processes incoming device data: filter by device type, check a threshold, trigger an alarm, forward to another system. The default “Root Rule Chain” handles basic message routing out of the box; building your first custom chain (a temperature threshold triggering an alert, for example) is the natural next step once devices are reporting data successfully.
Self-hosted CE vs ThingsBoard Cloud
It’s worth being clear about the actual choice here. ThingsBoard also offers a fully managed cloud version, where they handle hosting, scaling and updates for you, at a recurring cost. Self-hosting the Community Edition on your own VPS, as this guide covers, is free software running on infrastructure you already control, in exchange for handling your own updates, backups and scaling decisions. For most projects on this site, that trade favours self-hosting, but it’s worth knowing the managed option exists for teams that would rather not run the infrastructure themselves.
Onboarding your first device
With the platform running, connecting a real device is the natural next step. ThingsBoard’s device model: create a device in the web UI (Devices > Add device), which generates a unique access token. A device authenticates to ThingsBoard using that token over MQTT, publishing telemetry to a fixed topic structure:
mosquitto_pub -h your-server-ip -p 1883
-u "DEVICE_ACCESS_TOKEN"
-t "v1/devices/me/telemetry"
-m '{"temperature":21.5,"humidity":47}'That single command, run from any MQTT-capable client or device, is enough for a value to appear immediately in ThingsBoard’s device view, with no further configuration required, since the platform automatically creates the relevant data fields the first time it sees them.
Building your first dashboard widget
Once telemetry is flowing, ThingsBoard’s dashboard editor lets you drag a widget (a time-series chart, a gauge, a simple value card) onto a canvas and bind it to a device’s data, without writing any code. This is one of ThingsBoard’s clearest advantages over a hand-built Grafana setup for non-technical users on a team: the widget library covers most common visualisation needs out of the box, and binding a widget to a device is a few clicks rather than a query language.
Troubleshooting common problems
Installation script fails partway through. Usually insufficient RAM on the VPS; confirm at least 4GB is genuinely available with free -h before retrying, since the installer can fail silently or produce confusing errors when the system runs out of memory mid-install rather than reporting the resource shortage directly.
Web UI loads but shows a blank or broken dashboard. Often a browser cache issue after an upgrade; a hard refresh (Ctrl+Shift+R) resolves this more often than people expect before assuming something is genuinely broken server-side.
Devices show as “inactive” despite publishing data. Check the access token in the device’s publish command matches exactly what ThingsBoard generated, copy-paste errors here are the most common cause, and confirm the topic string is exactly v1/devices/me/telemetry, since ThingsBoard’s device API expects this specific format.
Docker container restarts repeatedly (crash loop). Check logs immediately with docker logs tb; the most common cause at this stage is a database connection failure, often because the install script hadn’t finished initialising the schema before the main service tried to start.
Why the database choice matters here
The PostgreSQL-backed single-instance deployment covered in this guide stores both entity data (devices, dashboards, users) and time-series telemetry in the same database, which is simple to manage and entirely sufficient for the device volumes most projects on this site deal with. Larger cluster deployments split this, using Cassandra specifically for time-series data at high write volumes, a genuinely different operational profile that most self-hosted projects never need to reach.
Frequently asked questions
Is ThingsBoard Community Edition really free?
Yes, it’s open-source under the Apache 2.0 licence. The Professional Edition adds enterprise features (multi-node clustering with paid support, advanced security modules) at a cost, but Community Edition covers everything in this guide.
Can ThingsBoard replace Node-RED entirely?
For most users, yes, ThingsBoard’s rule engine covers similar ground. Some people still run both, using Node-RED for complex cross-system integrations ThingsBoard’s rule engine isn’t designed for, while ThingsBoard handles device management and dashboards.
What database does ThingsBoard use?
PostgreSQL by default for the single-instance Docker deployment covered in this guide, which is sufficient for most projects. Cluster deployments can add Cassandra for time-series data at larger scale.
How do I upgrade ThingsBoard once it’s running?
ThingsBoard’s own documentation recommends upgrading sequentially through versions rather than skipping straight to the latest (for example v4.0 to v4.1 to v4.2, not v4.0 straight to v4.2), to keep the database schema migration process reliable.
Does ThingsBoard support multiple separate customers or tenants?
Yes, multi-tenancy is built in: a single ThingsBoard instance can host multiple tenants, each with their own users, devices and dashboards, isolated from each other. This is one of the platform’s genuine advantages for anyone managing IoT deployments across multiple clients or sites from one server.
User roles and permissions worth setting up early
Beyond the system administrator account created during install, ThingsBoard supports tenant administrators and customer users with progressively narrower permissions, useful the moment more than one person needs access. A tenant administrator manages devices, dashboards and rule chains for the whole deployment; a customer user typically sees only dashboards explicitly shared with them, with no access to device configuration or other customers’ data. Setting this up properly from the start, rather than sharing one admin login among several people, is worth the small extra effort, particularly given how easy it becomes to add later once a deployment has grown and migrating shared logins becomes more disruptive.
Alarms: turning data into action
Raw telemetry on a dashboard is useful for checking in manually; alarms are what make ThingsBoard proactive. An alarm rule, configured within a rule chain, watches incoming telemetry against a condition (a temperature exceeding a threshold, a device going silent for longer than expected) and creates a visible alarm record, optionally triggering a notification via email, SMS or a webhook to another system. This is functionally similar to the threshold-and-notify pattern covered in this site’s Node-RED guide, but built into the platform natively rather than requiring a separate flow to be built and maintained by hand.
Can I migrate from a hand-built MQTT/Node-RED/Grafana stack to ThingsBoard later?
Yes, since ThingsBoard speaks standard MQTT, existing devices generally just need reconfiguring with a new access token and broker address rather than a hardware or firmware change. Historical data in InfluxDB or another existing database typically needs a separate migration step, which is more involved than the device reconnection itself.
How do I back up a self-hosted ThingsBoard instance?
Back up the PostgreSQL database (a standard pg_dump works for the single-instance deployment) along with the mounted data and config volumes referenced in the Docker run command above. A VPS-level snapshot, taken regularly, is a simpler blanket approach that covers all of this at once for most small deployments.
Does ThingsBoard support device provisioning at scale, not just adding devices one at a time through the UI?
Yes, via its REST API and device provisioning features designed for fleets, useful once you’re deploying more devices than makes sense to add manually through the web interface one at a time.
Customising beyond the default widget library
For most projects, ThingsBoard’s built-in widget library covers everything needed, but it’s worth knowing the platform supports custom widget development for genuinely specific visualisation needs the built-in library doesn’t cover. This involves writing custom HTML, CSS and JavaScript within ThingsBoard’s widget editor, a meaningfully bigger undertaking than dragging a built-in widget onto a dashboard, and worth reaching for only once the standard library has genuinely been exhausted for a specific requirement rather than as a default starting point.
Can ThingsBoard send data onward to another system, not just display it?
Yes, rule chains can forward processed data to external systems via REST API calls, Kafka, or other integrations, making ThingsBoard usable as a central hub even when the final destination for some data is a separate analytics or business system.
How does ThingsBoard handle devices that report data infrequently, like once a day?
No different handling required; ThingsBoard stores telemetry as it arrives regardless of frequency, and dashboards display whatever data exists for the selected time range. Infrequent-reporting devices simply show sparser charts, which is expected and not a configuration issue to fix.
Is there a mobile app for ThingsBoard, or only the web dashboard?
ThingsBoard’s web dashboards are responsive and work reasonably well in a mobile browser; dedicated mobile apps exist primarily as part of the commercial PE/Cloud offering rather than the self-hosted CE deployment covered in this guide.
How does ThingsBoard compare to building the same thing in Grafana from scratch?
Grafana excels specifically at flexible, highly customised time-series visualisation; ThingsBoard adds device management, a rule engine and multi-tenancy on top of its own visualisation layer, a broader platform rather than a dashboard tool alone. Which fits better depends on whether device management and rule-based automation matter as much as the visualisation itself for your specific project.