74 lines
2.3 KiB
Markdown
74 lines
2.3 KiB
Markdown
# 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.
|