Plex, Sonarr, Radarr, Prowlarr, Sabnzbd, Bazarr, Tunarr, Pulsarr, Cleanuparr, Tdarr, Frigate

Prometheus, Grafana, Homepage, Uptime Kuma (external VPS)

DNS (BIND9 with DDNS), Reverse Proxy (Caddy), Tailscale subnet router

Personal website, Birdle (bird identification game), Terraria game server

Before starting, ensure you have the following:

Software Requirements

• Docker and Docker Compose
• Git
• SSH key pair for VM access
• Task (Taskfile runner) - Installation instructions

Initial Setup

# Clone the repository
git clone https://github.com/sfcal/homelab.git
cd homelab
Verify Taskfile is installed
task --version
View available tasks
task --list

Create a containerized environment with all necessary tools:

# Build the homelab execution container
task docker:exe
Create a convenient alias for running commands
Add to .bashrc
alias hl='docker run -it --rm \
  -v "$HOME/.ssh:/home/devops/.ssh" \
  -v "$HOME/.kube:/home/devops/.kube" \
  -v "$PWD:/workspace" \
  -v "$HOME/.home:/home/devops/.home" \
  -v "$HOME/.gitconfig:/home/devops/.gitconfig" \
  -e ENV=dev \
  homelab-exe'

Generate Ubuntu VM templates for your infrastructure:

Configure Packer Variables

• Create credentials file:

cd packer/environments/dev
cp credentials.dev.pkrvars.hcl.example credentials.dev.pkrvars.hcl

• Review environment variables:

# Check dev environment settings
cat environments/dev/ubuntu-variables.pkrvars.hcl

Important variables: These need to reflect if you are using local storage, ceph, or nfs

iso_file             = "local:iso/ubuntu-24.04.2-live-server-amd64.iso"
isostoragepool     = "ISOs-Templates"
storage_pool         = "vm-disks" storagepooltype    = "rbm" cloudinitstorage_pool = "vm-disks"

Build Templates

Choose your template and environment

# Build base Ubuntu template
hl task packer:build TEMPLATE=base ENV=dev
Build other templates as needed
hl task packer:build-ubuntu ENV=dev
hl task packer:build-debian ENV=dev
hl task packer:build-netboot ENV=dev

Deploy your VM infrastructure on Proxmox:

Configure Terraform Variables

• Create terraform variables:

cd terraform/environments/dev
cp terraform.tfvars.example terraform.tfvars

• Edit terraform.tfvars:

proxmoxapiurl          = "https://pve-01.home.example.com:8006/api2/json"
proxmoxapitoken_id     = "root@pam!terraform"
proxmoxapitoken_secret = "your-secret-here"
sshpublickey = "ssh-ed25519 AAAA..."
vms = {   "dns-server" = {     name          = "dns-server"     proxmox_node  = "pve-01"     vmid          = 201     template_name = "ubuntu-server-base"     ip_address    = "10.2.20.53/24"     gateway       = "10.2.20.1"     nameserver    = "10.2.20.1"     cores         = 2     memory        = 2048     disk_size     = "20G"     storage_pool  = "vm-disks"     ssh_user      = "devops"   }   # Add more VMs: media-stack, monitoring, reverse-proxy, etc. }

Deploy Infrastructure

# Deploy all VMs
hl task terraform:deploy ENV=dev
Or deploy a specific VM
hl task terraform:deploy-vm ENV=dev VM=dns-server

Install Docker and deploy services to your VMs:

Configure Ansible Variables

• Review inventory:

cd ansible
cat environments/dev/hosts.ini

• Configure environment settings:

# Global settings (domains, timezone, deploy path)
cat environments/dev/group_vars/all.yml
Unified services list (shared between DNS and reverse proxy)
cat environments/dev/group_vars/services.yml

The services.yml file is the single source of truth — it defines every service's subdomain, backend host/port, and whether it's proxied through Caddy.

Deploy Everything

# Deploy entire infrastructure in order
hl task ansible:deploy-all ENV=dev

Or Deploy Individual Stacks

# Infrastructure
hl task ansible:deploy-networking ENV=dev   # DNS + reverse proxy + Tailscale
hl task ansible:deploy-monitoring ENV=dev   # Prometheus, Grafana, Homepage
hl task ansible:deploy-external-monitoring ENV=dev  # Uptime Kuma (external VPS)
Applications
hl task ansible:deploy-media ENV=dev        # Full media stack
hl task ansible:deploy-website ENV=dev      # Personal website
hl task ansible:deploy-birdle ENV=dev       # Birdle game
hl task ansible:deploy-games ENV=dev        # Terraria server
Utilities
hl task ansible:ping ENV=dev               # Test connectivity
hl task ansible:backup-media ENV=dev       # Backup media configs
hl task ansible:restore-media ENV=dev      # Restore from backup

Verify Deployment

# Test connectivity to all hosts
hl task ansible:ping ENV=dev