MQTT for railway.app

Template Header

Deploy MQTT on railway.app with a single click.

✨ Features

MQTT with automated setup
Optional password authentication via MQTT_USER and MQTT_PASS
Timezone Support (Set timezone in environment variables)
Railway config as code via railway.toml

🏗️ Architecture

flowchart LR
    Client(["📡 MQTT Client"]) -->|"MQTT / TCP"| Proxy["Railway TCP Proxy"]
    Proxy -->|"TCP port 1883"| Entry["docker-entrypoint.sh"]
    Entry --> App["Container\neclipse-mosquitto"]
    App --> Volume[("Volume\n/mosquitto/data")]

🐍 How to Deploy

Click Deploy on Railway and setup your credentials in the environment variables

    TZ=Europe/Amsterdam
    MQTT_USER=yourusername
    MQTT_PASS=yourpassword
    PORT=1883 # Don't change this

Production recommendations (Railway)

Set both MQTT_USER and MQTT_PASS to enable authenticated access
If one of them is missing, broker starts in anonymous mode
Use persistent storage for /mosquitto/data
This data mount is enforced via requiredMountPath in railway.toml
Keep external TCP port mapped to 1883

Wait for Build & Deployment to Finish
Connect an MQTT client to the generated TCP proxy hostname and external port, using your credentials. MQTT has no HTTP login page.

The published template generates a broker password, maps the TCP proxy to port 1883, and mounts /mosquitto/data. The entrypoint gives Mosquitto access to its password file and data directory, and regenerates its password file atomically on restart. Logs go to stdout. The Docker healthcheck authenticates when credentials are configured; Railway's HTTP healthcheck is intentionally unset for this TCP service.

🐳 Local Development

docker compose up -d

Connect an MQTT client to localhost:1883, using the username and password from the Compose configuration.

Run the Docker integration tests (Docker and Node.js required):

docker build -t railwayapp-mqtt:test .
node --test tests/runtime.test.mjs