# 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.