jhodgkin/homelab-monitor

Fork 0

Files

T

jhodgkin a075488f4b

CI / web (push) Failing after 1m11s

Details

CI / api (push) Successful in 1m19s

Details

Scaffold homelab-monitor: Fastify API + React dashboard + CI

Vertical slice for Phase 1 (v1-dashboard milestone): Proxmox collector,
SQLite storage, local auth, and a dashboard UI showing host/container
status cards. Config-driven collector registry so future data sources
(SSH-based hosts, Zabbix, network discovery) plug in without rewiring.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-07-12 20:18:44 -06:00

2.9 KiB

Raw Blame History

Homelab Monitor — Project Memory

Unified health dashboard for the homelab (infra docs: jhodgkin/homelab repo, docs/infrastructure.md). One login instead of logging into Proxmox, Zabbix, OMV, and every service separately.

How to resume work in a new session

List open issues: GET /api/v1/repos/jhodgkin/homelab-monitor/issues?state=open&limit=30 on git.jerodrigged.com (same pattern as the main homelab backlog, see global ~/.claude/CLAUDE.md). Milestone v1-dashboard is the current focus; everything else is backlog.
Pick an issue, comment that you're starting it, do the work, comment what you did, close it.
Commit and push after every meaningful step — don't let work sit uncommitted.

Architecture

apps/api — Fastify + TypeScript. Polls collectors on an interval (POLL_INTERVAL_SECONDS, default 30s), writes snapshots to SQLite (apps/api/src/db), serves /api/*.
apps/web — React + Vite + TypeScript. Polls /api/hosts every 15s, renders host/container cards.
config/hosts.yaml — declares what to monitor (no secrets, committed). Credentials live in .env (gitignored) — see .env.example for the full list.
Collectors implement the Collector interface (apps/api/src/collectors/types.ts) and are registered in apps/api/src/index.ts. Adding a new data source = new collector + config entry, no other wiring.
- ProxmoxCollector (done): one API call to pve returns CPU/mem/disk and PSI pressure (pressurecpusome, pressurememoryfull) for the host + every LXC. Covers ~22 of ~24 machines.
- Everything else (SSH collector for .180/.171, network discovery, Zabbix alerts) is filed as backlog issues, not yet implemented.
Auth: local (bcrypt + signed session cookie) is live. AUTH_MODE=oidc is a stubbed config value only — Authentik wiring is issue #12, not implemented.

Infrastructure this project owns

Gitea repo: jhodgkin/homelab-monitor
Proxmox API token: monitor@pve!dashboard, role PVEAuditor (read-only), created via pveum on pve. Secret lives only in CT122's .env.
Deployment: CT122 (homelab-monitor, 192.168.1.103), unprivileged LXC on pve, Docker + Compose. SSH alias homelab-monitor in ~/.ssh/config (root, key-based). Not yet exposed externally — see issue #13 (needs NPM proxy host + Cloudflare tunnel route).

Known gaps / explicitly deferred (see issues for detail)

No historical charts yet — only the latest snapshot is shown (24h retention in SQLite unused by the UI so far).
No network device discovery yet.
No Zabbix/Graylog integration yet — this dashboard doesn't duplicate their alerting, just complements it later.
Public exposure and Authentik OIDC both need either credentials from the user or manual dashboard steps (Cloudflare Zero Trust, NPM admin UI, Authentik admin) — flagged in the relevant issues, not blocking.