KNEL/KNEL-TSYSDevStack-SupportStack-Cloudron

Files

T

mrcharles 0d7543704b feat: add ChirpStack Cloudron package (Infrastructure) [#668 ]

ChirpStack 4.19.1 (LoRaWAN network server) as the 14th package:
official-image wrapper, digest-pinned, with only bash added to the
upstream alpine runtime. Native OIDC login wired to the Cloudron
platform provider (openid_connect backend, config regenerated every
start); postgresql + redis addons; diesel migrations auto-run.
Operator config (NetID, US915 region, gateway MQTT backend) lives in
seeded files under /app/data/config. Build green; config generation
validated through chirpstack's own TOML parser. Docs gardened to 14
packages.

Ticket: https://projects.knownelement.com/issues/668

💘 Generated with Crush

Assisted-by: Crush:glm-5.2

2026-09-01 19:55:23 -05:00

3.9 KiB

Raw Blame History

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:

Set the env CHIRPSTACK_AUTH_MODE=internal and restart the app.
Log in as admin / admin, immediately set a strong password, and change the account email to your Cloudron login email.
Set CHIRPSTACK_AUTH_MODE back to openid_connect (or remove it) and restart.
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.

3.9 KiB Raw Blame History