Initial Meterbox commit with boot disk usage metric.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-19 02:45:52 +00:00
commit 4e44204d9b
@@ -0,0 +1,73 @@
+# Meterbox
+
+Reusable host resource dashboard. **Always run via Docker**, bound to localhost only.
+
+Rust collector + API, React charts for **CPU**, **memory**, and **network**.
+
+| Range | Bucket |
+|-------|--------|
+| 24 hours | 1 minute |
+| 7 days | 5 minutes |
+| 4 weeks | 30 minutes |
+| 3 months | 2 hours |
+
+## Install / start (Docker only)
+
+```bash
+cd /workspace/meterbox
+./scripts/up.sh
+# → http://127.0.0.1:8787
+```
+
+Stop:
+
+```bash
+./scripts/down.sh
+```
+
+Compose uses `network_mode: host` and `METERBOX_LISTEN=127.0.0.1:8787`:
+
+- No Docker port publish (`8787:8787` never used)
+- Does not DNAT around the host `INPUT REJECT`
+- Caddy/Rathole can proxy to `127.0.0.1:8787`
+- Host PID namespace for real host load/CPU visibility
+
+**Never** change the listen address to `0.0.0.0` or publish `0.0.0.0:8787` unless you explicitly want the dashboard on the public Internet.
+
+## Environment
+
+| Variable | Default (compose) | Meaning |
+|----------|-------------------|---------|
+| `METERBOX_LISTEN` | `127.0.0.1:8787` | Bind address (keep localhost) |
+| `METERBOX_DB` | `/app/data/meterbox.db` | SQLite path |
+| `METERBOX_STATIC` | `/app/frontend/dist` | Built UI |
+| `METERBOX_INTERVAL_SECS` | `30` | Sample period |
+| `METERBOX_RETENTION_DAYS` | `90` | Drop samples older than this |
+| `METERBOX_MAX_DB_BYTES` | `10737418240` (10 GiB) | Hard on-disk SQLite size cap |
+| `METERBOX_CLEANUP_INTERVAL_SECS` | `3600` | Periodic cleanup job cadence |
+
+### SQLite cleanup job
+
+A background job runs on startup (after ~15s) and every `METERBOX_CLEANUP_INTERVAL_SECS`:
+
+1. Deletes samples older than `METERBOX_RETENTION_DAYS`
+2. If on-disk size (`.db` + `-wal` + `-shm`) exceeds **10 GiB**, deletes oldest rows in batches until under ~90% of the cap
+3. Checkpoints WAL / `VACUUM`s when needed so deleted space is reclaimed
+
+An emergency size check also runs after each sample insert if the hard cap is breached.
+
+`GET /api/health` reports `db_bytes`, `max_db_bytes`, and retention settings.
+
+## API
+
+- `GET /api/health`
+- `GET /api/host`
+- `GET /api/snapshot`
+- `GET /api/series?range=24h|7d|4w|3m`
+
+## Install on another server
+
+1. Copy/clone this repo.
+2. `./scripts/up.sh`
+3. Reverse-proxy `127.0.0.1:8787` with Caddy/Rathole.
+4. Confirm with `sudo iptables -L -n -v` that Docker chains coexist safely with your host firewall.