Homelab Documentation¶
Welcome to the homelab infrastructure documentation. This site is generated from the homelab monorepo using mkdocs-material.
Published at: hldocs-c0acdec9.pages.dev
Changes under docs/, mkdocs.yml, or the docs workflow on main
auto-deploy via
GitHub Actions
to Cloudflare Pages (hldocs-c0acdec9.pages.dev).
Local preview: uv run mkdocs serve (see runbook).
What's Here¶
| Section | Description |
|---|---|
| Architecture | ADRs, live network/firewall, lab audit, OS patching |
| Hosts | Per-host docs — index table + key hosts (prox, infra-services) |
| Services | AdGuard + links to services/*/README.md in repo |
| Appliances | Network gear, NAS, managed appliances |
| Customer Apps | Apps with their own deploy pipelines |
| Security Register | Tracked findings and remediation status |
| Runbooks | Operational procedures |
| Journal | Check-ins and documentation validation evidence |
| Postmortems | Incident write-ups |
| Bus Factor | What someone else needs to know to keep the lights on |
Recent: 2026-08-09 live network · desk-side truth · session delta — UniFi/Prox live docs merged; desk-side tags/indexes/nav catch-up; runners and ops soak notes.
Key Principles¶
- Inventory is the source of truth. Hosts, services, and networks are defined
in
inventory/YAML files. Generators produce Ansible inventory, Prometheus targets, Homepage config, and doc stubs from that single source. mainis production.ansible-pullreconciles frommainevery 30 minutes. Coordinated OS patches run weekly frominfra-services(Phase 8). All changes go through PRs.- Secrets are encrypted in git. SOPS + age, with keys stored in 1Password.
- Entity boundaries matter. The repo manages different things differently — see the entity class table in PLAN.md.
Current Truth Map¶
| Question | Current source |
|---|---|
| What exists? | inventory/ YAML, generated Hosts, Services, and Customer Apps |
| What is live on the network? | Current Network, Firewall live posture, and recent journal entries |
| How is a service operated? | Service README under services/*/README.md plus linked runbooks |
| What security work remains? | Security Register and remediation PRs |
| What was the original target? | PLAN.md; do not use it as a live-state inventory |
Quick Links¶
- PLAN.md — master plan and execution spec
- Adding a Service — how to onboard a new service (Phase 4+)
- Secrets — bootstrap and rotation procedures (Phase 2+)