stan/website
1
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
16684d66882ba7f64586e1188d9a0af8b401e950
website/deploy/home-collector/README.md

3.7 KiB
Raw Blame History

home-collector

Feeds the private dashboard at /start (also the browser new-tab page). The app container has no Docker socket and must not get one, so a small stdlib-only Python script runs on the host every minute (systemd user timer home-collector.timer) and upserts two rows into home.snapshots:

key contents
host CPU %, load, uptime, RAM, swap, disk; every Docker container (state, health, restart count, CPU/mem via sudo docker); systemd timers (stan-backup*, postgres-backup*, disk-guard-*, house-scrape, b2-cost, groceries-import, money-sync, ned-collector-*) with last/next run and result; HTTP up/down + latency for each self-hosted service; latest ~/backups-cost/daily/*.json
ntfy the last 40 messages (72 h) from the ntfy topics in ~/.config/disk-guard.env (NTFY_URL) and ~/.config/house-scrape.env (HOUSE_NTFY_URL), plus NTFY_EXTRA. Only a label is stored, never the topic name.

The page reads both rows in the same parallel query batch as tasks and links, so a slow upstream never delays it; a snapshot older than 3 minutes is shown as stale.

Live stats (1 s)

On top of the minute snapshot, /start opens a Server-Sent Events stream (/start/live, owner only) while the tab is visible. The app reads netdata on the host (NETDATA_URL, default http://100.116.93.104:19999, the Tailscale-only bind) once a second through one shared poller (src/lib/server/live-stats.ts): host CPU, RAM, network, disk IO and per-container CPU/mem/state/health (netdata's docker and cgroups collectors), so the app still never touches the Docker socket. The poller stops 5 s after the last viewer leaves. The app container reaches netdata through one ufw rule: ufw allow in on br-c1585f0009ac from 172.26.0.0/16 to 100.116.93.104 port 19999 proto tcp (the backend compose network's bridge).

Setup

  1. A login role that may only upsert snapshots (created once, cluster superuser): CREATE ROLE home_collector LOGIN CONNECTION LIMIT 3 PASSWORD '…'; GRANT CONNECT ON DATABASE personal TO home_collector; The home migration grants USAGE on the schema and SELECT, INSERT, UPDATE on home.snapshots when the role exists (re-run those two GRANTs by hand if the role is created later).
  2. ~/.config/home-collector.env (mode 600): 
    HOME_DB_URL=postgresql://home_collector:…@127.0.0.1:5440/personal
# optional extra topics, e.g. the backup alerts from /etc/stan-backup:
# NTFY_EXTRA=backups=https://ntfy.sh/<topic>
  3. bash deploy/home-collector/install.sh (copies the script to ~/.local/bin/home-collector and enables the timer). Re-run after editing the script, e.g. to add a service to SERVICES.

Debug: python3 ~/.local/bin/home-collector --print, journalctl --user -u home-collector -n 20.