diff --git a/alert-bridge/README.md b/alert-bridge/README.md index e341509..636612d 100644 --- a/alert-bridge/README.md +++ b/alert-bridge/README.md @@ -70,6 +70,70 @@ curl -X POST http://localhost:8080/alerts \ -d '{"source":"ba-cronjob","message":"Started","level":"info"}' ``` +## Usage From Another LAN Host + +Deployed at `http://alert-bridge.home.arpa` (plain HTTP, not HTTPS — see +"Deployment" below for why). Any host on the home network can reach it +directly, no VPN/tunnel/cluster access needed: + +```bash +curl -X POST http://alert-bridge.home.arpa/alerts \ + -H "Authorization: Bearer $ALERT_BRIDGE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"source":"ba-cronjob","message":"Started","level":"info"}' + +# ... job runs ... + +curl -X POST http://alert-bridge.home.arpa/alerts \ + -H "Authorization: Bearer $ALERT_BRIDGE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"source":"ba-cronjob","message":"Finished with 0 errors","level":"info"}' +``` + +A `level=error` call additionally pings the configured `MENTION_USER_ID` in +Discord: + +```bash +curl -X POST http://alert-bridge.home.arpa/alerts \ + -H "Authorization: Bearer $ALERT_BRIDGE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"source":"ba-cronjob","message":"Finished with 3 errors","level":"error"}' +``` + +Reusable shape for a cronjob script — export `ALERT_BRIDGE_API_KEY` once at +the top (never hardcode the token in the script itself) and call `alert` at +each step: + +```bash +#!/usr/bin/env bash +set -euo pipefail + +ALERT_URL="http://alert-bridge.home.arpa/alerts" +SOURCE="ba-cronjob" + +alert() { + local level="$1" message="$2" + curl -sf -X POST "$ALERT_URL" \ + -H "Authorization: Bearer $ALERT_BRIDGE_API_KEY" \ + -H "Content-Type: application/json" \ + -d "{\"source\":\"$SOURCE\",\"message\":\"$message\",\"level\":\"$level\"}" \ + > /dev/null +} + +alert info "Started" + +if ! run_the_actual_job; then + alert error "Finished with errors" + exit 1 +fi + +alert info "Finished with 0 errors" +``` + +Since this is plain HTTP, the bearer token travels in cleartext on the LAN — +acceptable for a home network, but don't reuse `ALERT_BRIDGE_API_KEY` for +anything more sensitive. + ## Test And Build ```bash @@ -99,9 +163,17 @@ internal/telemetry/ # OpenTelemetry setup ## Deployment -Kubernetes manifests (Deployment/Service, and an internal-CA `IngressRoute` at -a `*.home.arpa` hostname so LAN callers outside the cluster can reach it) live -in the separate `homelab` repo, not here — not yet added as of this writing. +Kubernetes manifests (Deployment/Service, plus a plain-HTTP Traefik +`IngressRoute` at `alert-bridge.home.arpa` so LAN callers outside the cluster +can reach it) live in the separate `homelab` repo, not here. Deployed and +confirmed working as of 2026-08-01. + +The ingress is plain HTTP rather than the internal-CA HTTPS every other +`*.home.arpa` service uses — LAN callers (e.g. `nik-gpu`) don't have this +cluster's internal CA trusted, and installing it on every caller was judged +not worth it for an endpoint that's already bearer-token-authenticated and +LAN-only. See `homelab/manifests/home-services/alert-bridge-ingress.yaml`'s +header comment for the full reasoning. ## Limitations