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/ or mkdocs.yml on main auto-deploy via
GitHub Actions
to Cloudflare Pages (hldocs-c0acdec9.pages.dev).
Local preview: 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 |
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.
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+)