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.yml              # host definitions
  playbooks/
    bootstrap-minisforum.yml # OS hardening, packages, UFW, /data dirs
    setup-k3s.yml            # K3s server install, Helm, kubeconfig
  roles/
    common/                  # user, SSH hardening, UFW, base packages
    k3s-server/              # K3s server install + Helm
values/
  traefik.yml                ✅ deployed
  gitea.yml                  🔧 in progress
  pihole.yml                 🔧 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.yml ansible/playbooks/bootstrap-minisforum.yml

# Re-run K3s setup (idempotent)
ansible-playbook -i ansible/inventory.yml ansible/playbooks/setup-k3s.yml

# 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.yml

# 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.yml

# 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.yml

See Also

• migration-plan.md — full phase-by-phase migration plan