homelab-platform

Reusable infrastructure primitives for Proxmox-based homelabs. Provides the low-level building blocks that all service repos build on top of.

For deployed services (observability, DNS, etc.) see homelab-services.

---

What's Here

Path	What it is
.github/workflows/provision-vm.yml	Reusable workflow: Terraform + Ansible for any VM
terraform/modules/proxmox-vm/	Generic Proxmox VM module (cloud-init, DHCP via MAC)
terraform/modules/dns-record/	Single Technitium A record — compose with proxmox-vm to register VMs in DNS
ansible/base-vm.yml	Configures any service VM: Docker, runner, Node Exporter, Alloy
ansible/infra-runner.yml	Configures the terraform-runner VM itself
ansible/vars/main.yml	Platform defaults
ansible/templates/alloy-config.j2	Grafana Alloy log shipping template (deployed to every VM)
configs/alloy/alloy-config.alloy	Static Alloy config (for manual node setup)
docs/patterns/runner-tiers.md	The infra/service runner tier model
docs/nodes/terraform-runner/	How to bootstrap the infra runner
docs/examples/new-node/	Complete working example for a new VM node
docs/examples/new-vm-with-dns/	Same, but also registers a <name>.lan A record
docs/troubleshooting/	Common Proxmox provisioning and Ansible gotchas
docs/decisions/	Architecture decision records
docs/observability/	How observability agents work on every node
docs/deployment/	Runner management and multi-stage workflow patterns

---

Runner Tier Model

Two tiers — see docs/patterns/runner-tiers.md for full details.

Label	VM	Does
self-hosted-infra	terraform-runner	Runs Terraform + Ansible for all projects
self-hosted-service	any service VM	Hosts services; receives deployments

---

Using in a Project

1. Provision a VM

In your project repo, add a Terraform node config that uses the proxmox-vm module:

# services/my-service/terraform/main.tf
module "vm" {
  source = "github.com/BlakeHastings/homelab-platform//terraform/modules/proxmox-vm?ref=main"

  vm_name    = "my-vm"
  vm_id      = 202
  mac_address = "BC:24:11:00:02:02"
  # ... other vars
}

Then call the reusable workflow:

# .github/workflows/provision-my-vm.yml
jobs:
  provision:
    uses: BlakeHastings/homelab-platform/.github/workflows/provision-vm.yml@main
    with:
      vm_name: my-vm
      runner_label: my-vm                                  # specific label for targeted deploys
      runner_repo_url: https://github.com/your-org/your-repo
      terraform_working_dir: services/my-service/terraform
    secrets:
      PROXMOX_VE_ENDPOINT:         ${{ secrets.PROXMOX_VE_ENDPOINT }}
      PROXMOX_VE_API_TOKEN:        ${{ secrets.PROXMOX_VE_API_TOKEN }}
      PROXMOX_VE_SSH_USERNAME:     ${{ secrets.PROXMOX_VE_SSH_USERNAME }}
      PROXMOX_VE_SSH_PASSWORD:     ${{ secrets.PROXMOX_VE_SSH_PASSWORD }}
      ANSIBLE_PRIVATE_KEY:         ${{ secrets.ANSIBLE_PRIVATE_KEY }}
      GITHUB_ACTIONS_RUNNER_TOKEN: ${{ secrets.GITHUB_ACTIONS_RUNNER_TOKEN }}
      TF_VAR_PROXMOX_NODE:         ${{ secrets.TF_VAR_PROXMOX_NODE }}
      TF_VAR_TEMPLATE_ID:          ${{ secrets.TF_VAR_TEMPLATE_ID }}
      TF_VAR_GATEWAY:              ${{ secrets.TF_VAR_GATEWAY }}
      TF_VAR_SSH_PUBLIC_KEY:       ${{ secrets.TF_VAR_SSH_PUBLIC_KEY }}
# Note: secrets: inherit does NOT work cross-repo — each secret must be mapped explicitly

2. Deploy services to it

# .github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: [self-hosted, my-vm]    # matches runner_label from provision step
    steps:
      - uses: actions/checkout@v4
      - run: docker compose up -d

---

First-Time Setup

Bootstrap the terraform-runner once before anything else: → docs/nodes/terraform-runner/01-bootstrap.md

---

Adding a New VM to a Project

See docs/examples/new-node/ for complete working templates.

If using Claude Code: run /add-node in your project repo.

---

Documentation

Topic	Location
Runner tier model	docs/patterns/runner-tiers.md
Bootstrap terraform-runner	docs/nodes/terraform-runner/01-bootstrap.md
New VM example	docs/examples/new-node/
Observability agents (per-node)	docs/observability/overview.md
Proxmox provisioning gotchas	docs/troubleshooting/proxmox-provisioning.md
Ansible common gotchas	docs/troubleshooting/ansible-common-gotchas.md
Why dedicated infra runner	docs/decisions/terraform-runner-architecture.md
Secrets management	docs/decisions/secrets-management.md
Runner management	docs/deployment/runner-management.md
Multi-stage workflows	docs/deployment/multi-stage-workflows.md