Deploy and Host ThingsBoard IoT Platform on Railway

ThingsBoard is an open-source IoT platform for device connectivity, data collection, processing, visualization, and device management. This template deploys a production-ready stack of ThingsBoard, PostgreSQL, and Apache Kafka, wired over private networking, so you get a restart-safe IoT backend in one click.

Important: ThingsBoard deploys with default admin passwords. Change them right after your first login. See First-run setup under Implementation Details below.

About Hosting ThingsBoard IoT Platform

ThingsBoard connects devices over MQTT and HTTP, routes their telemetry through a rule engine, stores it in PostgreSQL, and renders it on customizable dashboards. A production deployment runs three coordinated services: the ThingsBoard node, a PostgreSQL database for entities and time-series data, and a Kafka broker for a durable message queue (the default in-memory queue loses in-flight data on restart). These services need private networking, persistent volumes, and the correct startup order. This template handles all of it: a single-broker Kafka in KRaft mode (no ZooKeeper), automatic schema installation on first boot, MQTT over TLS with a certificate created for your deployment, a healthcheck, and connection strings wired with reference variables, so you skip the assembly and debugging.

Common Use Cases

Ingesting and visualizing device/sensor telemetry (temperature, energy, GPS, industrial metrics)
Building IoT dashboards with alerting and automation via ThingsBoard's rule engine
Device management and provisioning for fleets of MQTT/HTTP-connected devices
A self-hosted alternative to SaaS IoT platforms

Dependencies for ThingsBoard IoT Platform Hosting

PostgreSQL (included): stores entities and time-series telemetry
Apache Kafka (included, single KRaft broker): the durable message queue for the rule engine

Deployment Dependencies

Implementation Details

Demo data. At deploy time you are asked to set LOAD_DEMO. Set it to true (lowercase) to include a sample tenant, devices, and dashboards for exploring the platform, or false for a clean install with only the system administrator. This applies to the first deploy only.

First run is slow. On the first deploy, ThingsBoard installs its database schema before it can serve traffic. This takes several minutes and includes one automatic restart: the service shows as deployed, briefly restarts, then stays up. Subsequent boots skip the install and start quickly.

First-run setup. Once it is running, open the ThingsBoard service URL and:

Log in as the system administrator: sysadmin@thingsboard.org / sysadmin.
Set the Base URL. Copy the REF_BASE_URL variable (ThingsBoard service → Variables) into System Settings → General → Base URL, then save. This screen is only visible to the sysadmin account, not tenant accounts.
Change the sysadmin password (avatar → Profile → Change password) and store it somewhere safe.
If you deployed with LOAD_DEMO=true, also log in as the demo tenant (tenant@thingsboard.org / tenant) and change that password, or delete the account.

Connecting and testing devices. Devices connect over MQTT with TLS (MQTTS) through the Railway TCP proxy, or over HTTPS (https://YOUR_THINGSBOARD_DOMAIN/api/v1/YOUR_ACCESS_TOKEN/telemetry). Plain MQTT on port 1883 is reachable only from other services in your project, over Railway's private network, so device access tokens never cross the internet unencrypted. CoAP and LwM2M are not supported because they require UDP.

MQTTS certificate. On first boot the template creates a certificate authority (CA) for your deployment and issues the MQTTS server certificate from it. Your devices must trust this CA. Download it from https://YOUR_THINGSBOARD_DOMAIN/api/device-connectivity/mqtts/certificate/download, or open a device in ThingsBoard and click Check connectivity, which shows the download command and a ready-made MQTTS command with your host and port. The CA is stored on the ThingsBoard volume and stays the same across redeploys.

To test MQTTS with Mosquitto: create a device in ThingsBoard, copy its access token, download the CA, then publish a reading. The host and port are on the ThingsBoard service's Networking tab (TCP proxy):

curl -o ca-root.pem https://YOUR_THINGSBOARD_DOMAIN/api/device-connectivity/mqtts/certificate/download
mosquitto_pub --cafile ca-root.pem -h TCP_PROXY_HOST -p TCP_PROXY_PORT -t v1/devices/me/telemetry -u YOUR_ACCESS_TOKEN -m '{"temperature":22.5}'

The value should appear under the device's Latest Telemetry in the ThingsBoard UI.

Why Deploy ThingsBoard IoT Platform on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying ThingsBoard IoT Platform on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.