fix: update the readmes to be more clear
This commit is contained in:
parent
dc7b8cbadd
commit
574a3a103e
6 changed files with 216 additions and 147 deletions
70
remote/README.md
Normal file
70
remote/README.md
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
# Remote Services
|
||||
|
||||
Cargo workspace with the server-side pieces of Noisebell. Runs on any Linux box.
|
||||
|
||||
| Service | Port | What it does |
|
||||
|---------|------|--------------|
|
||||
| [`cache-service/`](cache-service/) | 3000 | Polls the Pi, stores history in SQLite, fans out webhooks |
|
||||
| [`discord-bot/`](discord-bot/) | 3001 | Posts door status to a Discord channel |
|
||||
| [`rss-service/`](rss-service/) | 3002 | Serves an Atom feed of door events |
|
||||
| [`noisebell-common/`](noisebell-common/) | — | Shared types and helpers |
|
||||
|
||||
See each service's README for configuration and API docs.
|
||||
|
||||
## Building
|
||||
|
||||
```sh
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
Or with Nix:
|
||||
|
||||
```sh
|
||||
nix build .#noisebell-cache
|
||||
nix build .#noisebell-discord
|
||||
nix build .#noisebell-rss
|
||||
```
|
||||
|
||||
## NixOS deployment
|
||||
|
||||
The flake exports NixOS modules. Each service runs as a hardened systemd unit behind Caddy.
|
||||
|
||||
```nix
|
||||
{
|
||||
inputs.noisebell.url = "git+https://git.extremist.software/jet/noisebell?dir=remote";
|
||||
|
||||
outputs = { self, nixpkgs, noisebell, ... }: {
|
||||
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
|
||||
system = "x86_64-linux";
|
||||
modules = [
|
||||
noisebell.nixosModules.default
|
||||
({ ... }: {
|
||||
services.noisebell-cache = {
|
||||
enable = true;
|
||||
domain = "cache.noisebell.example.com";
|
||||
piAddress = "http://noisebell-pi:80";
|
||||
piApiKeyFile = "/run/secrets/noisebell-pi-api-key";
|
||||
inboundApiKeyFile = "/run/secrets/noisebell-inbound-api-key";
|
||||
outboundWebhooks = [{
|
||||
url = "http://localhost:3001/webhook";
|
||||
secretFile = "/run/secrets/noisebell-discord-webhook-secret";
|
||||
}];
|
||||
};
|
||||
services.noisebell-discord = {
|
||||
enable = true;
|
||||
domain = "discord.noisebell.example.com";
|
||||
discordTokenFile = "/run/secrets/noisebell-discord-token";
|
||||
channelId = "123456789012345678";
|
||||
webhookSecretFile = "/run/secrets/noisebell-discord-webhook-secret";
|
||||
};
|
||||
services.noisebell-rss = {
|
||||
enable = true;
|
||||
domain = "rss.noisebell.example.com";
|
||||
cacheUrl = "http://localhost:3000";
|
||||
};
|
||||
})
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
45
remote/cache-service/README.md
Normal file
45
remote/cache-service/README.md
Normal 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 |
|
||||
28
remote/discord-bot/README.md
Normal file
28
remote/discord-bot/README.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
# Discord Bot
|
||||
|
||||
Receives webhooks from the cache service and posts door status updates to a Discord channel as embeds.
|
||||
|
||||
- Green embed = door open
|
||||
- Red embed = door closed
|
||||
- Gray embed = Pi offline
|
||||
|
||||
Validates inbound webhooks with a Bearer token. Maintains a persistent Discord gateway connection with automatic reconnection.
|
||||
|
||||
## API
|
||||
|
||||
| Method | Path | Auth | Description |
|
||||
|--------|------|------|-------------|
|
||||
| `POST` | `/webhook` | Bearer | Status update from the cache service |
|
||||
| `GET` | `/health` | — | Health check |
|
||||
|
||||
## Configuration
|
||||
|
||||
NixOS options under `services.noisebell-discord`:
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `domain` | required | Caddy virtual host domain |
|
||||
| `discordTokenFile` | required | Discord bot token file |
|
||||
| `channelId` | required | Discord channel ID to post to |
|
||||
| `webhookSecretFile` | required | Shared secret with the cache service |
|
||||
| `port` | `3001` | Listen port |
|
||||
20
remote/rss-service/README.md
Normal file
20
remote/rss-service/README.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
# RSS Service
|
||||
|
||||
Serves an Atom feed of door status history. Stateless — it fetches from the cache service's `/history` endpoint on each request and renders the last 7 days as Atom XML.
|
||||
|
||||
## API
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `GET` | `/feed` | Atom feed |
|
||||
| `GET` | `/health` | Health check |
|
||||
|
||||
## Configuration
|
||||
|
||||
NixOS options under `services.noisebell-rss`:
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `domain` | required | Caddy virtual host domain |
|
||||
| `cacheUrl` | required | Cache service URL (e.g. `http://localhost:3000`) |
|
||||
| `port` | `3002` | Listen port |
|
||||
Loading…
Add table
Add a link
Reference in a new issue