homelab
Infrastructure-as-Code for a 3-machine homelab running K3s.
Status
| Phase | Description | Status |
|---|---|---|
| 0 | Backup configs, init repo | ✅ Done |
| 1 | Bootstrap Minisforum — K3s server + Traefik | ✅ Done |
| 2 | Join Debian as K3s agent, SMB setup | ⏳ Next |
| 3 | Deploy core infra — Gitea, Pi-hole, DDNS | 🔜 Planned |
| 4 | Deploy app services — Jellyfin, qBittorrent, etc. | 🔜 Planned |
| 5 | Networking cutover | 🔜 Planned |
| 6 | Cleanup legacy Debian services | 🔜 Planned |
Architecture
| Machine | IP | SSH Port | Role | Status |
|---|---|---|---|---|
| Minisforum UM780 XTX | 192.168.7.77 | 430 | K3s server | ✅ Running — K3s + Traefik |
| Debian Server (HP ProDesk) | TBD | — | K3s agent | ⏳ Phase 2 |
| Mac Mini M2 | TBD | — | Standalone | ⏳ Phase 3+ |
Repo Structure
ansible/
inventory.yml # host definitions
playbooks/ # top-level playbooks
roles/
common/ # base OS setup (users, SSH, UFW, packages)
k3s-server/ # K3s server install + Helm
k3s-agent/ # K3s agent join (Phase 2)
smb/ # Samba on Debian (Phase 2)
helm/ # custom Helm charts (if needed; most use upstream charts)
values/ # Helm values files per service
scripts/ # deploy-all.sh, porkbun-ddns.sh
old.debian-data/ # gitignored — backup of pre-migration configs
Prerequisites
- Ansible installed on your workstation:
pip install ansible - Ansible collections:
ansible-galaxy collection install community.general ansible.posix - SSH key at
~/.ssh/id_ed25519-nik-macbookair
Connecting
# SSH
ssh minisforum # port 430, configured via ~/.ssh/config
# Kubectl (after fetching kubeconfig)
export KUBECONFIG=/tmp/k3s-minisforum.yaml
kubectl get nodes
kubectl get pods -A
Deploying / Re-deploying
# Re-run bootstrap (idempotent)
ansible-playbook -i ansible/inventory.yml ansible/playbooks/bootstrap-minisforum.yml
# Re-run K3s setup (idempotent)
ansible-playbook -i ansible/inventory.yml ansible/playbooks/setup-k3s.yml
# Upgrade Traefik
helm upgrade --install traefik traefik/traefik \
--namespace traefik --create-namespace \
-f values/traefik.yml
See Also
- migration-plan.md — full phase-by-phase migration plan