homelab

Infrastructure-as-config for a 3-node personal homelab. Everything is declarative: Docker Compose (vps-apps, vps-net) and native systemd units (pi-home), plus runbooks. The machines are disposable; this repo plus the backups is the source of truth.

Owner: Javier · OS on all nodes: Debian (trixie)

Reference

• Nodes — the three machines, what runs where, data roots
• Networking — mesh, tunnels, routes, DNS, public ingress
• Data — config/data split and the backup matrix
• Runbooks — how to recover when something breaks

Each reference page describes the system as it is now. Change history lives in git, not here; tracked work lives in GitHub Issues on this repo.

Layout

One directory per node, one directory per app — always the same file names:

<node>/<app>/compose.yml      # the only compose file name we use
<node>/<app>/.env             # real secrets — gitignored, chmod 600
<node>/<app>/.env.example     # committed template, no real values
docs/runbooks/                # restore, node rebuild, cert renewal, netbird down

On vps-apps the repo is cloned at /opt/homelab. Deploys are per-app compose projects:

docker compose -f /opt/homelab/<node>/<app>/compose.yml up -d

House rules

1. Never publish a port on 0.0.0.0. Bind to the node's Netbird/tunnel IP or loopback.
2. Nothing is public. Services are reached over the mesh / tunnels; the only public ingress is the cloudflared tunnel on pi-home. Sensitive apps stay mesh-only with no public path.
3. Pin image tags to at least major/minor, never latest.
4. Never commit secrets.
5. No Docker socket in containers.
6. restart: unless-stopped, and mem_limit on pi-home.
7. Prefer editing this repo and deploying from it over ad-hoc node changes.

See CLAUDE.md for the full rules and the common commands.