jet/noisebell
jet/noisebell
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

fix: update the readmes to be more clear

Browse source
This commit is contained in:
Jet 2026-03-16 23:42:34 -07:00
parent dc7b8cbadd
commit 574a3a103e
No known key found for this signature in database
6 changed files with 216 additions and 147 deletions
Download patch file Download diff file Expand all files Collapse all files

45
remote/cache-service/README.md Normal file
View file

@ -0,0 +1,45 @@
# Cache Service
The central hub. Sits between the Pi and everything else.
It does two things: polls the Pi on a timer to keep a local copy of the door state, and receives push webhooks from the Pi when the state actually changes. Either way, updates get written to SQLite and forwarded to downstream services (Discord, etc.) via outbound webhooks.
If the Pi stops responding to polls (configurable threshold, default 3 misses), the cache marks it as offline and notifies downstream.
## API
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `GET` | `/status` | — | Current door status (`status`, `timestamp`, `last_seen`) |
| `GET` | `/info` | — | Cached Pi system info |
| `GET` | `/history` | — | Last 100 state changes |
| `POST` | `/webhook` | Bearer | Inbound webhook from the Pi |
| `GET` | `/health` | — | Health check |
## Configuration
NixOS options under `services.noisebell-cache`:
| Option | Default | Description |
|--------|---------|-------------|
| `domain` | required | Caddy virtual host domain |
| `piAddress` | required | Pi URL (e.g. `http://noisebell:80`) |
| `piApiKeyFile` | required | Key file for authenticating to the Pi |
| `inboundApiKeyFile` | required | Key file for validating inbound webhooks |
| `port` | `3000` | Listen port |
| `statusPollIntervalSecs` | `60` | How often to poll `GET /` on the Pi |
| `infoPollIntervalSecs` | `300` | How often to poll `GET /info` on the Pi |
| `offlineThreshold` | `3` | Consecutive failed polls before marking offline |
| `retryAttempts` | `3` | Outbound webhook retry count |
| `retryBaseDelaySecs` | `1` | Exponential backoff base delay |
| `httpTimeoutSecs` | `10` | HTTP request timeout |
| `dataDir` | `/var/lib/noisebell-cache` | SQLite database location |
| `outboundWebhooks` | `[]` | List of `{url, secretFile}` for downstream services |
## Secrets
| Secret | What it's for |
|--------|---------------|
| `piApiKeyFile` | Bearer token to poll the Pi's GET endpoints |
| `inboundApiKeyFile` | Bearer token the Pi sends when POSTing to `/webhook` |
| `outboundWebhooks[].secretFile` | Bearer token sent with outbound webhook POSTs |