mrcharles
0d7543704b
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
91 lines
3.9 KiB
Markdown
91 lines
3.9 KiB
Markdown
# 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.
|