Homelab Documentation¶

Documentation for the flomico.com homelab that spans repos: the overall architecture, why it's shaped the way it is, and records of exercises run against the live system. Repo-specific mechanics live in each repo's own README.md/CLAUDE.md; this is the layer above that.

The repos¶

Repo	Owns
`homelab-iac-common`	Shared building blocks: the `proxmox-vm` Terraform module, the `flomico.homelab` Ansible collection, the Bitwarden secret-loading shims, the toolbox container image, the reusable `deploy-stack.yml` workflow. Owns no infrastructure itself - publishes artifacts other repos pin at a version.
`homelab-platform`	The shared VMs that run containers: `apps01` (general-purpose, multi-tenant) and `obs01` (observability). Provisions hosts; does not deploy applications onto them.
`caddy-iac`	The Caddy reverse-proxy VM fronting `*.flomico.com` - the homelab's route registry and guest/admin traffic split.
`tailscale-iac`	Tailscale ACLs and split DNS for `flomico.com`.
`homelab-observability`	Grafana/Prometheus/Loki/Tempo stack on `obs01`.
`homelab-homepage`	The dashboard app, and the one service currently deployed through the full Terraform → Ansible → CI → `compose_stack` pipeline end to end.
`proxmox-iac` (planned)	Source control for the Proxmox hypervisor itself - network bridges, VLANs, storage pools, and eventually a from-scratch build procedure. See the tracked issue there for status.

How a change travels¶

flowchart LR
  subgraph common["homelab-iac-common"]
    MOD["terraform module<br/>proxmox-vm"]
    COL["ansible collection<br/>flomico.homelab"]
    IMG["toolbox image<br/>ghcr.io/codyecsl/homelab-toolbox"]
    WF["reusable workflow<br/>deploy-stack.yml"]
  end

  MOD -->|git module source| PLAT["homelab-platform"]
  IMG --> PLAT
  IMG --> SVC["service repos<br/>homelab-homepage, ..."]
  WF --> SVC

  PLAT -->|terraform apply| HOST["apps01<br/>192.168.10.101"]
  SVC -->|deploy| HOST
  HOST -->|reverse_proxy| CADDY["caddy-iac"]

See the Runbook for the step-by-step of each of the four everyday scenarios (stand up a service, update one, change a route, change something shared) - it used to live in homelab-iac-common, moved here 2026-08-06 since it's about how the whole fleet operates, not that one repo. This page covers the layer above the runbook: why, and what's been proven to actually work.

The real goal: disaster recovery¶

The pattern (Terraform + Ansible + a versioned shared collection, deployed via CI) started as an exercise in scalability patterns. The goal that actually matters now is disaster recovery: rebuild the homelab on new hardware, assuming the source drives are gone but TrueNAS (long-term data) and the Bitwarden vault (secrets) survive. See Architecture for the full reasoning, and DR Drills for what's actually been tested against that goal.