Homelab

Infrastructure documentation, Ansible configs, and runbooks for my homelab.

Quick Links


🗺️ Network Topology	IP map, VLANs, DNS
🖥️ Hosts	Per-machine reference
⚙️ Services	Per-service reference
📖 Runbooks	Step-by-step procedures
🗓️ Decision Log	Why things are the way they are

Hosts at a Glance

Hostname	Role	IP	OS
`proxmox-main`	Primary Proxmox node, arr stack, Jellyfin	`192.168.x.x`	Proxmox VE
`pbs`	Proxmox Backup Server (HP MicroServer Gen8)	`192.168.x.x`	PBS
`optiplex-3020`	Networking/proxy services	`192.168.x.x`	Proxmox VE
`optiplex-3070`	Stateful services	`192.168.x.x`	Proxmox VE

Update this table as hosts are added or change role.

Services at a Glance

Service	Host	Port
Jellyfin	`proxmox-main`	`8096`
WireGuard	`optiplex-3020`	`51820/udp`
Vaultwarden	`optiplex-3020`	`8080`
Reverse Proxy	`optiplex-3020`	`80/443`

Repo Layout

homelab/
├── ansible/          # Inventory, playbooks, roles
├── docker/           # Docker Compose configs per service
├── docs/             # This documentation
│   ├── hosts/
│   ├── services/
│   ├── network/
│   ├── runbooks/
│   └── decisions/
└── .gitea/workflows/ # CI/CD pipelines

Common Tasks

# Run full site playbook (safe to re-run anytime)
make deploy

# Bootstrap a brand-new machine
make bootstrap HOST=optiplex-3070

# Dry-run to preview changes
make check

# Lint Ansible
make lint

Secrets

Secrets are never committed. Use .env.example files as templates. Sensitive Ansible vars are encrypted with Ansible Vault.

# Edit a vault-encrypted file
ansible-vault edit ansible/group_vars/all/vault.yml

Contributing / Updating

Update the relevant doc before making infrastructure changes
Keep the hosts/services tables above in sync
Log significant decisions in docs/decisions/ with today's date