jhodgkin
a075488f4b
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>
46 lines
2.9 KiB
Markdown
46 lines
2.9 KiB
Markdown
# 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
|
|
|
|
1. 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.
|
|
2. Pick an issue, comment that you're starting it, do the work, comment what you did, close it.
|
|
3. 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.
|