meterbox/README.md

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)

cd /workspace/meterbox
./scripts/up.sh
# → http://127.0.0.1:8787

Stop:

./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 / VACUUMs 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.