Metadata-Version: 2.4
Name: fastpluggy-homelab-overview
Version: 0.1.1
Summary: Unified homelab dashboard plugin — replaces the static home.lab page with a live, plugin-aware view
Author: FastPluggy Team
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: FastPluggy>=0.4.33
Requires-Dist: fastpluggy-fp-deployer>=0.2.0
Requires-Dist: fastpluggy-auth-user>=0.2.0
Requires-Dist: fastpluggy-tasks-worker>=0.2.44
Requires-Dist: loguru>=0.7.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml
Requires-Dist: httpx
Provides-Extra: tests
Requires-Dist: pytest>=7.0; extra == "tests"
Requires-Dist: pytest-cov>=4.0; extra == "tests"
Requires-Dist: pytest-asyncio>=0.21; extra == "tests"
Requires-Dist: respx>=0.20; extra == "tests"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: e2e
Requires-Dist: fastpluggy-cli; extra == "e2e"

# homelab_overview

Unified homelab dashboard plugin for FastPluggy. Replaces the static `home.lab` page (auto-generated from `hosts.yml`) with a live, plugin-aware view that adds zone grouping, backend health probes, kiosk mode, and history graphs.

## What it does

- Reads `hosts.yml` (via `fp_deployer`'s `InfraReader`) as the always-on primary source — host list, services, DNS, ports, repo/CI links
- Aggregates live data from other plugins when present (network, docker, ecosystem_status, metrics)
- Renders three views: **Hosts** (zone-grouped service cards), **Services** (regrouped by service type with replication insight), **Kiosk** (full-screen wall display)
- Probes service health on a schedule and persists a rolling history per service for sparkline-style latency display

## Architecture (high level)

| Layer | Source |
|-------|--------|
| **Tier 1** (always available) | `hosts.yml` via `InfraReader` |
| **Tier 2** (best-effort enrichment) | `network` / `network_node` / `docker_plugin` / `ecosystem_status` / `metrics` |

The plugin owns minimal data collection of its own — it's primarily a view + light-aggregation layer. See `wip-ia-code/plans/homelab-overview.md` in `fp-ecosystem` for the full plan.

## Hard dependencies

- `FastPluggy>=0.4.0`
- `fastpluggy-fp-deployer>=0.2.0` — `InfraReader` + Deploy-elsewhere action
- `fastpluggy-auth-user>=0.2.0` — admin gating for write routes
- `fastpluggy-tasks-worker>=0.2.44` — health-probe scheduler

## Routes

| Route | Access |
|-------|--------|
| `GET /dashboard` | Public read (Hosts + Services view) |
| `GET /kiosk` | Public read |
| `GET /api/homelab/panels` | Public read |
| `GET /api/homelab/panels/render` | Public read (HTML partial for the JS auto-refresh) |
| `GET /api/homelab/sources` | Public read |
| `GET /api/homelab/health` | Public read |
| `GET /api/homelab/network-map` | Public read (stub until #169 ships) |
| `GET /api/homelab/settings` | Admin |
| `PUT /api/homelab/settings` | Admin |
| `POST /api/homelab/settings/reset` | Admin |
| `POST /api/homelab/services/{name}/deploy-elsewhere` | Admin |
| `GET /settings` | Admin |

## Settings

Configurable from `/settings` (admin-only) or by editing the DB-backed
settings table directly:

| Field | Default | Purpose |
|-------|---------|---------|
| `lab_name` | `"Home Lab"` | Header label |
| `infra_repo_path` | `/data/infra/` | Volume-mounted hosts.yml path |
| `groups_to_show` | `["homelab", "ovh"]` | hosts.yml `group:` values to render |
| `theme_default` | `"auto"` | Light / Dark / Auto (system) |
| `refresh_interval_seconds` | 30 | Browser auto-refresh cadence |
| `probe_interval_seconds` | 30 | Backend prober cadence |
| `probe_timeout_seconds` | 5.0 | Per-probe timeout |
| `probe_history_size` | 100 | Rolling-window rows per service |
| `probe_default_tls_verify` | `False` | Self-signed `*.lab` certs |
| `probe_alert_down_minutes` | 5 | "Down for >N min" alert threshold |
| `kiosk_data_refresh_seconds` | 30 | Kiosk-mode probe re-poll cadence |
| `kiosk_screen_rotate_seconds` | 30 | Kiosk-mode screen-rotate cadence |

## Kiosk

`GET /kiosk` renders a dark-glow auto-rotating dashboard designed for the
`--kiosk` browser flag on always-on screens. See [`docs/kiosk-setup.md`](docs/kiosk-setup.md)
for the Chromium / RPi setup recipe.

## Migration from the static `home.lab` page

This plugin replaces the static HTML page formerly generated by
`infrastructure/scripts/generate.py`. See [`docs/migration-from-static.md`](docs/migration-from-static.md)
for the cutover checklist and rollback steps.

## Screenshots

Screenshots are auto-generated by CI and committed to `docs/screenshots/e2e/`.

## Local dev

See `dev/run_local.py`.

## License

MIT
