# APC UPS Dashboard

A production-ready FastAPI + Redis dashboard for monitoring multiple APC UPS devices via `apcupsd` NIS. Single-admin auth (argon2 + session cookies), CSRF, rate limiting, security headers, SSE live updates, 7-day history, connection-health tracking, battery degradation trends, HTML email alerts with batching and silent-hours, and Prometheus metrics.

## Features

**Monitoring**
- Multiple UPS managed dynamically via UI/REST (stored in Redis)
- Real-time dashboard with SSE, fleet-overview panel, per-UPS state indicators
- 7-day snapshot history, per-minute watts averages, daily energy + cost
- Connection-health tracker — COMMLOST detection after 3× interval, recovery INFO alerts
- Battery-health sampling (1/min) with 7-day trend + decline %
- CSV export (history/events/energy), event log, alert management + ack

**Alerts (email-only)**
- Severity taxonomy: CRITICAL (ONBATT/COMMLOST/RUNTIME_LOW/BCHARGE_LOW), WARNING (LOAD_HIGH/REPLACEBATT/SELFTEST_FAIL/TEMP_HIGH/XFER_BURST/VOLT_DEV), INFO (REACHABLE/LINE_RESTORED)
- Coalesced HTML emails (one per UPS per poll cycle), severity-colored
- 30-min per-message cooldown, silent-hours deferral (CRITICAL always delivered), retries via tenacity
- Test-email button and optional daily summary

**Security & ops**
- Single-admin auth (argon2 password, signed session cookie, double-submit CSRF)
- SSRF host validation (rejects loopback/link-local; private IPs gated by `ALLOW_PRIVATE_IPS`)
- SMTP password **only** from env — never persisted to Redis
- Subprocess timeout on `apcaccess` (10s), rate-limiting on auth/config, security headers + CSP
- Non-root container (UID 10001), digest-pinned `python:3.14.5-slim` multi-stage build
- `/healthz`, `/readyz`, `/metrics` (Prometheus), JSON structured logs with request-ID correlation
- GitHub Actions pipeline runs ruff + pytest before building/publishing the image

## Quick start (docker-compose)

```bash
cp .env.example .env
# Required in production — edit .env:
#   SESSION_SECRET=<run: python -c "import secrets; print(secrets.token_urlsafe(48))">
#   SMTP_PASSWORD=<your SMTP password, if using alerts>
docker compose up --build
```

Open http://localhost:10280 — the app redirects to `/setup` where you create the admin account on first boot. Subsequent visits require login.

## Environment variables

| Var | Required | Default | Notes |
|---|---|---|---|
| `SESSION_SECRET` | yes (prod) | ephemeral | 32+ random bytes, signs session cookies |
| `ADMIN_USERNAME` | no | `admin` | |
| `ADMIN_PASSWORD_HASH` | no | unset | Skip setup wizard by pre-seeding an argon2 hash |
| `REDIS_URL` | no | `redis://redis:6379/0` | Supports `redis://:pw@host:port/db` |
| `SMTP_PASSWORD` | no | unset | Read only from env, never stored |
| `ALLOW_PRIVATE_IPS` | no | `true` | Set false to block RFC1918 UPS hosts |
| `TRUST_PROXY` | no | `false` | Enable Secure cookies + HSTS when behind HTTPS proxy |
| `LOG_LEVEL` | no | `INFO` | DEBUG/INFO/WARNING/ERROR |
| `SESSION_MAX_AGE_SECONDS` | no | `1209600` | 14 days |
| `RATE_LIMIT_ENABLED` | no | `true` | Disable in tests |
| `TZ` | no | `UTC` | |

Generate values:
```bash
# SESSION_SECRET
python -c "import secrets; print(secrets.token_urlsafe(48))"
# ADMIN_PASSWORD_HASH (optional pre-seed)
python -c "from passlib.hash import argon2; print(argon2.hash('mysecret'))"
```

> **Heads-up — `$` escaping in `.env`:** argon2 hashes look like `$argon2id$v=19$m=...$<salt>$<hash>`. Docker Compose treats `$word` as variable substitution in `.env`, so pasting a raw hash produces warnings (`The "argon2id" variable is not set…`) and the container receives a mangled, unverifiable hash — you won't be able to log in. Quoting does **not** help. Either double every `$` (`$$argon2id$$v=19$$m=...`), or skip this variable entirely and use the `/setup` wizard (recommended).

## apcupsd server requirements

Your remote APC UPS hosts must run `apcupsd` with the Network Information Server (NIS) enabled:

1. Install: `sudo apt-get install apcupsd`
2. Edit `/etc/apcupsd/apcupsd.conf`:
   ```
   UPSTYPE usb
   NISIP 0.0.0.0
   NISPORT 3551
   NETSERVER on
   ```
3. Restart: `sudo systemctl restart apcupsd`
4. Test: `apcaccess status` and `nc -vz <server-ip> 3551`

## Development

Production Docker builds install `requirements.txt`; local development and CI use
`requirements.dev.txt`.

```bash
python3.14 -m venv .venv && . .venv/bin/activate
pip install -r requirements.dev.txt

# Run tests (uses fakeredis)
pytest tests/

# With coverage
coverage run -m pytest tests/ && coverage report

# Lint
ruff check .

# Local dev server (needs apcaccess binary + REDIS_URL env)
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

## Persistence

Config and history live in Redis via an AOF-backed `redis-data` volume. To wipe state:
```bash
docker compose down && docker volume rm apcupsd-client_redis-data
```

## API (summary)

| Path | Auth | Notes |
|---|---|---|
| `/` (dashboard), `/config`, `/events`, `/alerts`, `/settings` | session | Jinja pages |
| `/login`, `/setup`, `/logout` | open/session | |
| `/healthz`, `/readyz`, `/metrics` | open | Prom metrics on `/metrics` |
| `GET /api/stream` | session | SSE snapshots |
| `GET /api/ups`, `/api/ups/{name}/{status\|history\|events\|energy\|health\|battery_health}` | session | |
| `GET /api/ups/fleet/overview` | session | Aggregate fleet summary |
| `GET /api/ups/{name}/export?format=csv&kind=history\|events\|energy&since_days=N` | session | Streaming CSV |
| `GET /api/events`, `/api/alerts`, `/api/alerts/active` | session | |
| `POST /api/alerts/{id}/ack` | session+CSRF | |
| `GET/POST/PUT/DELETE /api/config/{ups,smtp,ui}/...` | session (+CSRF for writes) | Rate-limited |

## License

MIT