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
parent 10e2b7c7ed
commit 0d7543704b
11 changed files with 570 additions and 11 deletions
@@ -0,0 +1 @@
+repo/
@@ -0,0 +1,13 @@
+# ChirpStack Cloudron package - optional env knobs
+# (set via `cloudron env set`, restart to apply)
+#
+# Authentication backend. Default: openid_connect (Cloudron SSO).
+# Use "internal" ONLY for the one-time admin bootstrap described in
+# README.md, then switch back.
+CHIRPSTACK_AUTH_MODE=openid_connect
+
+# Auto-register users on first SSO login (true/false).
+CHIRPSTACK_OIDC_REGISTRATION=true
+
+# Log level: trace | debug | info | warn | error.
+CHIRPSTACK_LOG_LEVEL=info
@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.0.0 — 2026-09-01
+
+Initial Cloudron package (ChirpStack 4.19.1, ticket
+[#668](https://projects.knownelement.com/issues/668)).
+
+- Official-image wrapper around `chirpstack/chirpstack:4.19.1` (digest
+  pinned); only addition to the runtime image is `bash` for `start.sh`.
+- Native OIDC login against the Cloudron platform identity provider;
+  admin bootstrap path documented (temporary `internal` auth mode).
+- PostgreSQL + Redis addons; diesel migrations auto-run at startup;
+  persistent API JWT secret under `/app/data`.
+- Config split into a per-boot generated fragment and operator-owned
+  `50-network.toml` + `region_us915_0.toml` under `/app/data/config/`.
+- Env knobs: `CHIRPSTACK_AUTH_MODE`, `CHIRPSTACK_OIDC_REGISTRATION`,
+  `CHIRPSTACK_LOG_LEVEL`.
@@ -0,0 +1,25 @@
+{
+  "manifestVersion": 2,
+  "type": "app",
+  "id": "io.cloudron.chirpstack",
+  "title": "ChirpStack",
+  "description": "Open-source LoRaWAN network server: manage gateways, devices, tenants and integrations from a web interface. Users log in via OIDC (Cloudron single sign-on); PostgreSQL stores all state, Redis handles sessions and de-duplication. LoRaWAN gateways connect through an external MQTT broker configured per region.",
+  "author": "Orne Brocaar",
+  "website": "https://www.chirpstack.io/",
+  "contactEmail": "cloudron@tsys.dev",
+  "tagline": "LoRaWAN network server with web UI",
+  "version": "4.19.1",
+  "healthCheckPath": "/",
+  "httpPort": 8080,
+  "memoryLimit": 512,
+  "addons": {
+    "localstorage": true,
+    "postgresql": {
+      "version": "16"
+    },
+    "redis": {}
+  },
+  "mediaLinks": [],
+  "changelog": "Initial Cloudron package for ChirpStack 4.19.1 (official-image wrapper). Native OIDC login wired to the Cloudron platform identity provider (user_authentication.openid_connect from CLOUDRON_OIDC_* env); PostgreSQL addon for storage with auto-run diesel migrations; Redis addon for sessions and de-duplication. Config is split into a generated platform fragment (rewritten each start) and operator-owned files under /app/data/config (network NetID, regions, gateway MQTT backend) editable with the Cloudron file manager. US915 region seeded by default.",
+  "icon": "file://logo.png"
+}
@@ -0,0 +1,51 @@
+# ChirpStack Cloudron Package
+#
+# ChirpStack is an open-source LoRaWAN network-server: web UI + gRPC/REST
+# API on a single port, PostgreSQL for storage, Redis for sessions /
+# deduplication / OIDC state, and an external MQTT broker for gateway
+# connectivity and integrations (configured per region, not embedded).
+#
+# Upstream: https://github.com/chirpstack/chirpstack
+#   - Official Docker image chirpstack/chirpstack:4.19.1 (alpine, single
+#     static musl binary /usr/bin/chirpstack, upstream runs it as
+#     nobody:nogroup with ENTRYPOINT /usr/bin/chirpstack)
+#   - Takes a config DIRECTORY via `chirpstack --config <dir>`; every *.toml
+#     in it is concatenated (tables must not collide across files) and
+#     ${ENV_VAR} placeholders are substituted
+#   - DB schema migrations (diesel, embedded) run automatically at startup
+#     and seed an internal `admin` user
+#
+# Authentication: NATIVE OIDC (preferred). start.sh regenerates
+# /app/data/config/10-cloudron.toml on every start, wiring the Cloudron
+# platform OIDC provider (CLOUDRON_OIDC_ISSUER / CLIENT_ID / CLIENT_SECRET)
+# into [user_authentication.openid_connect]. CHIRPSTACK_AUTH_MODE=internal
+# is kept as an operator escape hatch for admin bootstrap only (see README).
+#
+# Pattern: official-image wrapper. Building the Rust workspace + pnpm UI
+# from source is a multi-GB compile; the upstream image is the supported
+# distribution channel. Image pinned by tag AND digest (amd64 manifest
+# digest of the 4.19.1 tag, verified via docker manifest inspect).
+FROM chirpstack/chirpstack:4.19.1@sha256:c749015e640b8cf33338c08b12922896b17636feb06e421abdd3cc80f1cdc6b9
+
+# bash is the only addition: start.sh uses it for the addon wait loops
+# (bash /dev/tcp) and TOML generation. Kept as root only for apk; the
+# runtime user stays the upstream nobody:nogroup.
+USER root
+RUN apk add --no-cache bash
+
+# start.sh waits for the postgresql + redis addons, seeds the persistent
+# config fragments under /app/data/config/ and execs chirpstack.
+# Made executable on the host, not at build time (Cloudron builds hit
+# permission errors on RUN chmod).
+COPY start.sh /app/start.sh
+
+WORKDIR /app/data
+
+# Cloudron exposes the web UI / REST / gRPC on this port (api.bind in the
+# generated config). No other TCP listener is enabled by default: gateway
+# connectivity is outbound MQTT to an external broker.
+EXPOSE 8080
+
+USER nobody:nogroup
+
+ENTRYPOINT ["/bin/bash", "/app/start.sh"]
@@ -0,0 +1,90 @@
+# ChirpStack — Cloudron Package
+
+[ChirpStack](https://www.chirpstack.io/) 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](https://projects.knownelement.com/issues/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
+
+```bash
+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.
@@ -0,0 +1,261 @@
+#!/bin/bash
+set -euo pipefail
+
+# ChirpStack runtime setup:
+#   1. wait for the Cloudron postgresql + redis addons
+#   2. persist the API JWT secret (rotating it would invalidate tokens)
+#   3. regenerate /app/data/config/10-cloudron.toml on EVERY start so addon
+#      credentials and OIDC secrets are always current (Cloudron rotates
+#      addon passwords on restore / migration)
+#   4. seed the operator-owned config fragments ONCE (network + region);
+#      these are meant to be edited with the Cloudron file manager and
+#      survive restarts
+#   5. exec chirpstack (diesel migrations run automatically at startup)
+#
+# Config layout (chirpstack concatenates every *.toml in --config <dir>;
+# tables must not repeat across files):
+#   10-cloudron.toml        generated: [logging] [postgresql] [redis] [api]
+#                           [user_authentication] - DO NOT hand-edit
+#   50-network.toml         seeded once: [network] (net_id, enabled_regions)
+#   region_*.toml           seeded once: [[regions]] blocks (gateway MQTT
+#                           backend, channel plan, region network overrides)
+
+CONFIG_DIR="/app/data/config"
+GENERATED_CONF="${CONFIG_DIR}/10-cloudron.toml"
+NETWORK_CONF="${CONFIG_DIR}/50-network.toml"
+SECRET_FILE="/app/data/.api_jwt_secret"
+
+mkdir -p "${CONFIG_DIR}"
+
+# --- 1. wait for the addons -------------------------------------------------
+wait_tcp() {
+  local host="$1" port="$2" name="$3"
+  echo "Waiting for ${name} at ${host}:${port} ..."
+  until (exec 3<>"/dev/tcp/${host}/${port}") 2>/dev/null; do
+    echo "${name} is unavailable - sleeping"
+    sleep 2
+  done
+  echo "${name} is up"
+}
+
+wait_tcp "${CLOUDRON_POSTGRESQL_HOST:-127.0.0.1}" "${CLOUDRON_POSTGRESQL_PORT:-5432}" "PostgreSQL"
+wait_tcp "${CLOUDRON_REDIS_HOST:-127.0.0.1}" "${CLOUDRON_REDIS_PORT:-6379}" "Redis"
+
+# --- 2. persistent API JWT secret --------------------------------------------
+if [[ ! -s "${SECRET_FILE}" ]]; then
+  ( umask 077; head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n' > "${SECRET_FILE}" )
+  echo "Generated new API JWT secret"
+fi
+API_SECRET="$(cat "${SECRET_FILE}")"
+
+# --- 3. generated platform config (rewritten on every start) -----------------
+toml_escape() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  printf '%s' "${s}"
+}
+
+DB_HOST="${CLOUDRON_POSTGRESQL_HOST:-127.0.0.1}"
+DB_PORT="${CLOUDRON_POSTGRESQL_PORT:-5432}"
+DB_NAME="${CLOUDRON_POSTGRESQL_DATABASE:-chirpstack}"
+DB_USER="$(toml_escape "${CLOUDRON_POSTGRESQL_USERNAME:-chirpstack}")"
+DB_PASSWORD="$(toml_escape "${CLOUDRON_POSTGRESQL_PASSWORD:-chirpstack}")"
+PG_DSN="postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}?sslmode=disable"
+
+# Cloudron redis requires auth; prefer the platform-provided URL.
+if [[ -n "${CLOUDRON_REDIS_URL:-}" ]]; then
+  REDIS_SERVERS="$(toml_escape "${CLOUDRON_REDIS_URL}")"
+else
+  REDIS_PASSWORD="$(toml_escape "${CLOUDRON_REDIS_PASSWORD:-}")"
+  REDIS_SERVERS="redis://:${REDIS_PASSWORD}@${CLOUDRON_REDIS_HOST:-127.0.0.1}:${CLOUDRON_REDIS_PORT:-6379}"
+fi
+
+AUTH_MODE="${CHIRPSTACK_AUTH_MODE:-openid_connect}"
+OIDC_REGISTRATION="${CHIRPSTACK_OIDC_REGISTRATION:-true}"
+LOG_LEVEL="${CHIRPSTACK_LOG_LEVEL:-info}"
+OIDC_ISSUER="$(toml_escape "${CLOUDRON_OIDC_ISSUER:-}")"
+OIDC_CLIENT_ID="$(toml_escape "${CLOUDRON_OIDC_CLIENT_ID:-}")"
+OIDC_CLIENT_SECRET="$(toml_escape "${CLOUDRON_OIDC_CLIENT_SECRET:-}")"
+APP_ORIGIN="$(toml_escape "${CLOUDRON_APP_ORIGIN:-}")"
+
+cat > "${GENERATED_CONF}" <<EOF
+# Generated by start.sh on every boot - manual edits will be lost.
+# Operator config belongs in 50-network.toml / region_*.toml (seeded once).
+
+[logging]
+level = "${LOG_LEVEL}"
+
+[postgresql]
+dsn = "${PG_DSN}"
+max_open_connections = 10
+connection_recycling_method = "verified"
+
+[redis]
+servers = ["${REDIS_SERVERS}"]
+max_open_connections = 100
+
+[api]
+bind = "0.0.0.0:8080"
+secret = "${API_SECRET}"
+
+[user_authentication]
+enabled = "${AUTH_MODE}"
+
+[user_authentication.openid_connect]
+provider_url = "${OIDC_ISSUER}"
+client_id = "${OIDC_CLIENT_ID}"
+client_secret = "${OIDC_CLIENT_SECRET}"
+redirect_url = "${APP_ORIGIN}/auth/oidc/callback"
+logout_url = "${APP_ORIGIN}"
+login_redirect = true
+login_label = "Cloudron"
+registration_enabled = ${OIDC_REGISTRATION}
+assume_email_verified = false
+scopes = ["openid", "email", "profile"]
+EOF
+chmod 600 "${GENERATED_CONF}"
+echo "Generated platform config at ${GENERATED_CONF} (auth mode: ${AUTH_MODE})"
+
+# --- 4. operator config (seeded once, survives restarts) ----------------------
+if [[ ! -f "${NETWORK_CONF}" ]]; then
+  cat > "${NETWORK_CONF}" <<'EOF'
+# Operator configuration - seeded on first start, safe to edit with the
+# Cloudron file manager (changes apply on restart).
+#
+# Do NOT add [postgresql], [redis], [api], [user_authentication] or
+# [logging] here: those tables are owned by the generated 10-cloudron.toml
+# and chirpstack fails to parse duplicate tables.
+
+[network]
+# NetID (3 bytes, hex) - MUST be changed to a unique value for this
+# network. 000000-0000FF is reserved for private / experimental networks
+# (see LoRa Alliance NetID assignments).
+net_id = "000001"
+
+# Enabled regions; each entry must match the id of a [[regions]] block in
+# one of the region_*.toml files in this directory. More region files can
+# be copied from the upstream repo (chirpstack/configuration/).
+enabled_regions = ["us915_0"]
+EOF
+  echo "Seeded network config at ${NETWORK_CONF}"
+fi
+
+if [[ ! -f "${CONFIG_DIR}/region_us915_0.toml" ]]; then
+  cat > "${CONFIG_DIR}/region_us915_0.toml" <<'EOF'
+# US915 region (channels 0-7 + 64) - the standard US915 sub-band plan.
+# Verbatim from upstream chirpstack/configuration/region_us915_0.toml;
+# edit the gateway MQTT backend below to point at your broker.
+
+[[regions]]
+id = "us915_0"
+description = "US915 (channels 0-7 + 64)"
+common_name = "US915"
+user_info = ""
+
+[regions.gateway]
+force_gws_private = false
+
+[regions.gateway.backend]
+enabled = "mqtt"
+
+[regions.gateway.backend.mqtt]
+topic_prefix = "us915_0"
+share_name = "chirpstack"
+server = "tcp://localhost:1883"
+username = ""
+password = ""
+qos = 0
+clean_session = false
+client_id = ""
+keep_alive_interval = "30s"
+ca_cert = ""
+tls_cert = ""
+tls_key = ""
+
+[[regions.gateway.channels]]
+frequency = 902300000
+bandwidth = 125000
+modulation = "LORA"
+spreading_factors = [7, 8, 9, 10]
+
+[[regions.gateway.channels]]
+frequency = 902500000
+bandwidth = 125000
+modulation = "LORA"
+spreading_factors = [7, 8, 9, 10]
+
+[[regions.gateway.channels]]
+frequency = 902700000
+bandwidth = 125000
+modulation = "LORA"
+spreading_factors = [7, 8, 9, 10]
+
+[[regions.gateway.channels]]
+frequency = 902900000
+bandwidth = 125000
+modulation = "LORA"
+spreading_factors = [7, 8, 9, 10]
+
+[[regions.gateway.channels]]
+frequency = 903100000
+bandwidth = 125000
+modulation = "LORA"
+spreading_factors = [7, 8, 9, 10]
+
+[[regions.gateway.channels]]
+frequency = 903300000
+bandwidth = 125000
+modulation = "LORA"
+spreading_factors = [7, 8, 9, 10]
+
+[[regions.gateway.channels]]
+frequency = 903500000
+bandwidth = 125000
+modulation = "LORA"
+spreading_factors = [7, 8, 9, 10]
+
+[[regions.gateway.channels]]
+frequency = 903700000
+bandwidth = 125000
+modulation = "LORA"
+spreading_factors = [7, 8, 9, 10]
+
+[[regions.gateway.channels]]
+frequency = 903000000
+bandwidth = 500000
+modulation = "LORA"
+spreading_factors = [8]
+
+[regions.network]
+installation_margin = 10
+rx_window = 0
+rx1_delay = 1
+rx1_dr_offset = 0
+rx2_dr = 8
+rx2_frequency = 923300000
+rx2_prefer_on_rx1_dr_lt = 0
+rx2_prefer_on_link_budget = false
+downlink_tx_power = -1
+adr_disabled = false
+min_dr = 0
+max_dr = 3
+enabled_uplink_channels = [0, 1, 2, 3, 4, 5, 6, 7, 64]
+
+[regions.network.rejoin_request]
+enabled = false
+max_count_n = 0
+max_time_n = 0
+
+[regions.network.class_b]
+ping_slot_dr = 8
+ping_slot_frequency = 0
+EOF
+  echo "Seeded region config at ${CONFIG_DIR}/region_us915_0.toml"
+fi
+
+# --- 5. run -------------------------------------------------------------------
+# chirpstack applies the embedded diesel migrations on startup, then serves
+# the web UI + gRPC/REST API on 0.0.0.0:8080.
+echo "Starting ChirpStack ..."
+exec /usr/bin/chirpstack --config "${CONFIG_DIR}"