INIT

README.md

@@ -0,0 +1,90 @@
+# metrica
+
+AI README PLACEHOLDER
+
+```
+POST /api/{script}/     push JSON   (requires a token)
+GET  /api/{script}/     read JSON   (requires a token)
+GET  /                  dashboard   (open)
+GET  /health            liveness
+```
+
+## Quick start
+
+```bash
+# 1. configure a token (or let the app print a temporary one on first start)
+cp .env.example .env
+$EDITOR .env
+
+# 2. run it (uv installs deps into an ephemeral env automatically)
+uv run app.py
+# → http://127.0.0.1:8000
+```
+
+If you don't set `METRICA_TOKENS`, the app generates a temporary token and
+prints it to the console on startup.
+
+## Pushing data
+
+Any valid token authorizes any script. A script is auto-created the first time
+it pushes — no registration step.
+
+```bash
+TOKEN=change-me-token-1
+
+# a single number
+curl -X POST http://127.0.0.1:8000/api/nightly-backup/ \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "$(ls /var/backups | wc -l)"
+
+# a structured payload
+curl -X POST http://127.0.0.1:8000/api/disk-check/ \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"files": 1423, "used_gb": 38.2, "status": "ok"}'
+```
+
+`X-API-Key: $TOKEN` works as an alternative to the `Authorization` header.
+
+The dashboard draws a sparkline from the first numeric value it finds in each
+payload (so both examples above chart automatically).
+
+### From cron
+
+```cron
+# count files in a directory every hour
+0 * * * * curl -sf -X POST https://metrica.example.com/api/inbox-count/ \
+  -H "Authorization: Bearer $METRICA_TOKEN" \
+  -d "$(ls /srv/inbox | wc -l)"
+```
+
+## Storage
+
+Each script is one file: `data/{script}.jsonl`. Every push appends one line:
+
+```json
+{"ts": "2026-07-08T16:42:00Z", "data": {"files": 1423, "used_gb": 38.2}}
+```
+
+Delete a script by deleting its file. Trim history with `tail`. Back it up by
+copying the `data/` directory.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `METRICA_TOKENS` | *(generated)* | Comma/space-separated valid push tokens |
+| `METRICA_TOKENS_FILE` | – | File of tokens, one per line |
+| `METRICA_DATA_DIR` | `data` | Where JSONL files are written |
+| `METRICA_MAX_HISTORY` | `100` | Recent points shown per script |
+| `METRICA_HOST` / `METRICA_PORT` | `127.0.0.1` / `8000` | Bind address |
+
+## Notes on security
+
+- The **push and read APIs require a token**; script names are restricted to
+  `[A-Za-z0-9_-]` so they can't escape the data directory.
+- The **dashboard is open** (read-only). If the metrics are sensitive, keep the
+  service on a private network or put a reverse proxy / VPN / basic-auth in
+  front of `/`.
+- Always run behind HTTPS in production so tokens aren't sent in clear text.