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 |
🔧 In progress |
| 4 |
Deploy app services — Jellyfin, qBittorrent, JDownloader, Dashy, Glances |
🔜 Planned |
| 5 |
Networking cutover — router, Traefik ingress, DNS |
🔜 Planned |
| 6 |
Cleanup legacy Debian services |
🔜 Planned |
Architecture
| Machine |
IP |
SSH Port |
Role |
Status |
| Minisforum UM780 XTX |
192.168.7.77 |
430 |
K3s server, main gateway |
✅ Running — K3s + Traefik |
| Debian Server (HP ProDesk) |
TBD |
— |
K3s agent, SMB storage |
⏳ Phase 2 |
| Mac Mini M2 |
TBD |
— |
Standalone (outside cluster) |
⏳ Phase 3+ |
Internal Services (Minisforum)
| Service |
URL |
Notes |
| Traefik |
— |
Ingress controller, Let's Encrypt |
| Gitea |
https://gitea.home.arpa |
Git + Docker registry, SSH on port 2222 |
| Pi-hole |
https://pihole.home.arpa/admin |
Primary DNS, resolves *.home.arpa → 192.168.7.77 |
Repo Structure
ansible/
inventory.yaml # host definitions
playbooks/
bootstrap-minisforum.yaml # OS hardening, packages, UFW, /data dirs
setup-k3s.yaml # K3s server install, Helm, kubeconfig
roles/
common/ # user, SSH hardening, UFW, base packages
k3s-server/ # K3s server install + Helm
values/
traefik.yaml ✅ deployed
gitea.yaml 🔧 in progress
pihole.yaml 🔧 in progress
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.yaml ansible/playbooks/bootstrap-minisforum.yaml
# Re-run K3s setup (idempotent)
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/setup-k3s.yaml
# Traefik
helm repo add traefik https://helm.traefik.io/traefik && helm repo update
helm upgrade --install traefik traefik/traefik \
--namespace traefik --create-namespace \
-f values/traefik.yaml
# Gitea
helm repo add gitea-charts https://dl.gitea.com/charts/ && helm repo update
helm upgrade --install gitea gitea-charts/gitea \
--namespace gitea --create-namespace \
-f values/gitea.yaml
# Pi-hole
helm repo add mojo2600 https://mojo2600.github.io/pihole-kubernetes/ && helm repo update
helm upgrade --install pihole mojo2600/pihole \
--namespace pihole --create-namespace \
-f values/pihole.yaml
See Also
