KNEL-TSYSDevStack-SupportStack-Cloudron/Package-Workspace/Infrastructure/chirpstack

ChirpStack — Cloudron Package

ChirpStack is an open-source LoRaWAN network-server: it manages gateways, devices, tenants, device-profiles and integrations, and exposes a web UI plus gRPC / REST APIs from a single port. Packaged as an official-image wrapper around the upstream chirpstack/chirpstack:4.19.1 image (pinned by digest).

• Upstream: https://github.com/chirpstack/chirpstack (MIT)
• Ticket: #668
• Category: Infrastructure · Pattern: official-image wrapper + start.sh config generation

Authentication (auth gate verdict: ✅ OIDC preferred)

ChirpStack 4 ships a native OpenID Connect backend ([user_authentication.openid_connect]). start.sh wires the Cloudron platform OIDC provider (CLOUDRON_OIDC_ISSUER / CLOUDRON_OIDC_CLIENT_ID / CLOUDRON_OIDC_CLIENT_SECRET) with redirect_url = ${CLOUDRON_APP_ORIGIN}/auth/oidc/callback, so logins go through Cloudron SSO. Registration is enabled: the first SSO login auto-creates the user.

Admin bootstrap (one-time)

The DB migration seeds an internal admin user (email admin, password admin, is_admin = true). Users created via OIDC registration are regular (non-admin) users. To become admin over SSO:

1. Set the env CHIRPSTACK_AUTH_MODE=internal and restart the app.
2. Log in as admin / admin, immediately set a strong password, and change the account email to your Cloudron login email.
3. Set CHIRPSTACK_AUTH_MODE back to openid_connect (or remove it) and restart.
4. Log in via SSO: ChirpStack links the OIDC identity to the existing user by email, granting the admin role.

Until step 2 is done the seeded admin account keeps its default password — do the bootstrap right after installing.

Addons & ports

Concern	Cloudron wiring
Storage	postgresql addon (diesel migrations auto-run at startup)
Sessions / dedup / OIDC state	redis addon (CLOUDRON_REDIS_URL)
Files	localstorage (/app/data)
Web UI + gRPC + REST	single HTTP port 8080 (api.bind)

LoRaWAN gateways do not connect to this app directly: ChirpStack 4 consumes an external MQTT broker per region (see /app/data/config/region_*.toml). Point regions.gateway.backend.mqtt at your broker (e.g. a Mosquitto container/app) and configure integrations the same way.

Configuration layout

chirpstack --config <dir> concatenates every *.toml in the directory; tables must not repeat across files. /app/data/config/ is split:

File	Written	Owns
10-cloudron.toml	every start	[logging] [postgresql] [redis] [api] [user_authentication] — regenerated, never hand-edit
50-network.toml	first start	[network] (NetID, enabled regions)
region_us915_0.toml	first start	US915 [[regions]] block incl. gateway MQTT backend

Operator knobs live in 50-network.toml and the region files — edit them with the Cloudron file manager; changes apply on restart. Change net_id from the seeded 000001 to a unique value for your network, and point the region MQTT backend at a real broker. The API JWT secret is persisted at /app/data/.api_jwt_secret.

Environment knobs (.env.example)

Variable	Default	Purpose
CHIRPSTACK_AUTH_MODE	openid_connect	internal only for admin bootstrap (see above)
CHIRPSTACK_OIDC_REGISTRATION	true	auto-register unknown SSO users
CHIRPSTACK_LOG_LEVEL	info	trace / debug / info / warn / error

Build & install

docker build --cgroup-parent ukrrs-batch.slice -t chirpstack-cloudron:test \
  Package-Workspace/Infrastructure/chirpstack/

cloudron build && cloudron install on the Cloudron VPS for real deployment. First start waits for PostgreSQL + Redis, seeds config and runs migrations automatically.