Skip to content

Homelab Documentation

Find a procedure, locate a system, or understand a change. Start with the task—not the repository layout.

Start with a task

What's Here

  • Runbooks — procedures grouped by task, from incident response to routine maintenance.
  • Infrastructure — network, compute, appliances, platform design, and decision records.
  • Services — service guides and operator manuals, plus customer apps.
  • Security — tracked risks and remediation; operator handover explains critical access and dependencies.
  • History — journals, dated scans, reviews, postmortems, and retired systems.

Use Search for a hostname, service, error, or task. Search includes historical pages; check the date and lifecycle status before following a result.

Current Truth Map

  • What exists: inventory YAML and the host, service, and appliance directories. A definition is not proof a service is running.
  • Network posture: the network and firewall captures record observations dated 2026-08-09. Verify against the live system before making changes.
  • How to operate it: the relevant runbook and service operator manual. Manuals linked to GitHub require access to the private repository.
  • What changed: the journal records dated observations and remaining gates; old checkmarks are not current acceptance evidence.
  • Original intent: PLAN.md is the execution plan, not a live-state inventory.

Key Principles

  • Inventory is the source of truth. inventory/ YAML drives generated configuration and documentation stubs.
  • main is production. Infrastructure changes go through reviewed PRs; do not use documentation cleanup as a reason to change running systems.
  • Secrets stay encrypted. SOPS + age, with keys stored in 1Password. This documentation site is public.
  • Ownership boundaries matter. Check the entity classes before changing a system.