Deploy and Host ChirpStack on Railway

Built for an LLM agent to deploy and use. There is no setup wizard and nothing to fill in: the admin password, the API secret and every database and broker password are generated at deploy time, the admin user exists from the first boot, and the contract below lists every URL, variable name and one script that proves it works.

ChirpStack is an open-source LoRaWAN network server: it manages gateways, devices, applications and device profiles, handles joins and uplinks and schedules downlinks, and hands device data to your application over MQTT or an HTTP/gRPC API. This template runs the full stack, a self-hosted alternative to The Things Stack and other hosted LoRaWAN network servers.

About Hosting ChirpStack

This template runs five services: chirpstack (the official chirpstack/chirpstack image, version 4.20.0), rest-api (the official chirpstack/chirpstack-rest-api image, a JSON/REST front for the ChirpStack gRPC API), postgres (Postgres 17 with the pg_trgm and hstore extensions ChirpStack needs), redis and mosquitto (an MQTT broker with password authentication and a public TCP proxy). Postgres, Redis and Mosquitto each sit on a volume. The ChirpStack configuration is written at boot from the service variables, with the regions EU868, US915 (sub-band 0), AS923 and AU915 (sub-band 0) enabled, each on its own MQTT topic prefix (eu868, us915_0, as923, au915_0).

The ChirpStack web UI is on the chirpstack service domain. The first sign-in is user admin with ADMIN_PASSWORD; the password is reapplied on every boot. Gateways connect to the broker over MQTT (the public TCP proxy of the mosquitto service): run the ChirpStack Gateway Bridge on the gateway, or use a Basic Station or Semtech packet-forwarder setup that speaks MQTT, with user chirpstack and password MQTT_PASSWORD. The UDP packet-forwarder protocol on port 1700 is not available on Railway, because Railway has no UDP ingress.

Agent contract

Public URL (UI and gRPC / gRPC-web API): https:// plus the RAILWAY_PUBLIC_DOMAIN of the chirpstack service, used below as CS_URL
Public URL (REST API): https:// plus the RAILWAY_PUBLIC_DOMAIN of the rest-api service, used below as REST_URL. Swagger UI is at /.
Private URL: http://chirpstack.railway.internal:8080 (gRPC and UI), http://rest-api.railway.internal:8080 (REST), mosquitto.railway.internal:1883 (MQTT)
Public MQTT: MOSQUITTO_PUBLIC_HOST:MOSQUITTO_PUBLIC_PORT (the TCP proxy of the mosquitto service)
Credentials: ADMIN_PASSWORD (user admin) on the chirpstack service; MQTT_PASSWORD on the mosquitto service (user chirpstack)
Auth: sign in once to get a JWT, then send it to the REST API as the header Grpc-Metadata-Authorization: Bearer $JWT. The script below signs in with a gRPC-web call (POST $CS_URL/api.InternalService/Login), which needs only ADMIN_PASSWORD. MQTT clients use username chirpstack and MQTT_PASSWORD; anonymous MQTT is refused.
Health: GET $CS_URL/ returns 200 with no credentials

# run with CS_URL, REST_URL, ADMIN_PASSWORD, MQTT_HOST, MQTT_PORT and MQTT_PASSWORD set
EMAIL=admin
BODY=$(printf '\n%b%s\022%b%s' "\\$(printf %03o ${#EMAIL})" "$EMAIL" "\\$(printf %03o ${#ADMIN_PASSWORD})" "$ADMIN_PASSWORD")
JWT=$( (printf '\000\000\000\000%b' "\\$(printf %03o ${#BODY})"; printf %s "$BODY") | curl -s -X POST "$CS_URL/api.InternalService/Login" -H 'content-type: application/grpc-web+proto' -H 'x-grpc-web: 1' --data-binary @- | tr -c '[:print:]' ' ' | grep -o 'eyJ[A-Za-z0-9_.-]*' | head -1)
echo "jwt ${#JWT} chars"
curl -s -o /dev/null -w 'ui %{http_code}\n' "$CS_URL/"
curl -s -o /dev/null -w 'rest-no-token %{http_code}\n' "$REST_URL/api/tenants?limit=5"
curl -s -G "$REST_URL/api/tenants" --data-urlencode limit=5 -H "Grpc-Metadata-Authorization: Bearer $JWT" | grep -o '"name":"[^"]*"'
mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" -u chirpstack -P "$MQTT_PASSWORD" -t test/agent -m ok; echo "mqtt-exit $?"

A fresh deploy prints a JWT length above zero, ui 200, rest-no-token 401, "name":"ChirpStack" and mqtt-exit 0. From there the REST API lists and creates gateways, applications, device profiles and devices (/api/gateways, /api/applications, /api/devices), and application data arrives on the MQTT topics application/APPLICATION_ID/device/DEV_EUI/event/up.

Why Deploy ChirpStack 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 ChirpStack 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.

Agent-ready - generated secrets, a contract block and one working script; no wizard before the first API call.
Full stack in one deploy - network server, REST API, Postgres, Redis and an authenticated MQTT broker, wired together over the private network.
Redeploy-safe - every database and the broker sit on volumes; passwords and the API secret are stable across redeploys.
Pinned image - ChirpStack is pinned to 4.20.0 in the template, so a redeploy never changes the server version underneath you.

Common Use Cases

Private LoRaWAN network - run your own network server for sensors, meters and trackers without a hosted LoRaWAN subscription.
IoT data pipelines - subscribe an application, database or AI agent to device uplinks over MQTT.
Fleet management by API - register gateways and devices from a script through the REST API.

Dependencies for ChirpStack Hosting

Postgres 17 with pg_trgm and hstore, Redis 7 and an MQTT broker (Mosquitto 2), all included in this template.
One or more LoRaWAN gateways that can reach the public MQTT proxy of the mosquitto service.

Deployment Dependencies

chirpstack/chirpstack - upstream network server
ChirpStack documentation - gateways, device profiles, integrations and the API
chirpstack/chirpstack-rest-api - the REST API front