Skip to content

Quick Start

Deploy the homelab from scratch in four steps.

Note

Complete the Prerequisites first. You need Proxmox API tokens, an SSH key, and an Age key before proceeding.

1. Clone and Configure

git clone git@github.com:sfcal/homelab.git
cd homelab

Set your environment (defaults to dev):

export ENV=wil

2. Build VM Templates

Build the base Ubuntu template on Proxmox:

task packer:build-ubuntu ENV=wil

This creates a cloud-init-enabled Ubuntu Server template with Docker, Node Exporter, and Lazydocker pre-installed.

Tip

Debian templates are also available: task packer:build-debian ENV=wil

3. Provision VMs

Deploy all VMs defined in terraform/environments/wil/vms.auto.tfvars:

task terraform:deploy ENV=wil

To provision a single VM:

task terraform:deploy-vm ENV=wil VM=networking

Warning

The networking VM must be provisioned first — it provides DNS for all other VMs.

4. Deploy Services

Deploy the full infrastructure stack:

task ansible:deploy-all ENV=wil

Or deploy services individually, in dependency order:

task ansible:deploy-networking ENV=wil     # DNS, Caddy, Tailscale
task ansible:deploy-ca ENV=wil             # Step-CA certificate authority
task ansible:deploy-ntp ENV=wil            # Chrony time server
task ansible:deploy-monitoring ENV=wil     # Prometheus, Grafana, Homepage
task ansible:deploy-media ENV=wil          # Plex, *arr stack

5. Verify

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

# Check a specific service
curl -k https://wil.5am.cloud

Next Steps

Troubleshooting

Packer build fails with 401 — Check Proxmox API token credentials in packer/environments/wil/credentials.wil.pkrvars.hcl. Ensure the token has VM.Allocate and Datastore.AllocateSpace permissions.

Terraform can't find template — The template name must match what Packer created. Check with qm list on the Proxmox host. Template names follow the pattern ubuntu-server-<env>-base.

Ansible can't connect — Verify the VM is running (qm status <vmid>), the IP is correct in hosts.ini, and your SSH key is authorized.

DNS not resolving — The networking VM must be deployed first. Other VMs use it as their nameserver (10.2.20.53 in WIL).