Homelab Infrastructure as Code

Homelab Infrastructure as Code

Overview

This is a Proxmox homelab managed as Infrastructure as Code. All changes go through Terraform or Ansible. SSH is read-only for debugging.

Quick Reference

Containers

SSH: Use aliases from ~/​.ssh/​config (e.g., ssh ripper, ssh jellyfin).

Directory Structure

terraform/
  proxmox-homelab/   # LXC containers (one .tf per container)
  tailscale/         # VPN configuration
  cloudflare/        # DNS records
  lldap/             # LDAP users/​groups

ansible/
  playbooks/         # Service playbooks
  roles/             # Reusable roles
  vars/​*_secrets.yml # Vault-encrypted secrets

nixos/               # Devbox NixOS config
flake.nix            # Nix devshells

Secrets

Terraform Workflow

Always: plan → review → apply → verify

cd terraform/<module>
terraform fmt
terraform validate
terraform plan          # REQUIRED before apply

Present plan summary to user. Ask: "Does this look correct?"

After approval:

terraform apply

Verify resources exist, update docs/​reference/​current-state.md if needed.

Ansible Workflow

Always: lint → check → apply → verify

cd ansible
ansible-lint --offline
ansible-playbook playbooks/<service>.yml --syntax-check
ansible-playbook playbooks/<service>.yml --check   # REQUIRED dry-run

Present changes to user. Ask: "Does this look correct?"

After approval:

ansible-playbook playbooks/<service>.yml

Long-running playbooks (jellyfin, transcoder, proxmox-host): Use 600000ms timeout.

Verify via SSH: systemctl status <service>, journalctl -u <service>.

Nix DevShells

All commands require the devshell. Verify with which terraform.

direnv allow    # Auto-load (recommended)
nix develop     # Manual entry

If tools are missing, the devshell isn't loaded. See root CLAUDE.md for troubleshooting.

Adding a New Container

This is a multi-step workflow. See add-container.md for the complete checklist.

Quick overview:

1. Create terraform/​proxmox-homelab/<name>.tf
2. Run Terraform workflow (plan → apply)
3. Add to Ansible inventory
4. Create playbook and roles
5. Run Ansible workflow (check → apply)
6. Update documentation

Common Operations

Scale Container Resources

Edit CPU/​memory in terraform/​proxmox-homelab/<name>.tf, run Terraform workflow.

Add Ansible Role to Existing Container

1. Create ansible/​roles/<name>/ with tasks/​handlers/​templates
2. Add role to playbook
3. Run Ansible workflow

GPU Passthrough

Requires coordination:

• Terraform: Container privileged, features.nesting=true
• Ansible: GPU passthrough role delegates to Proxmox host

See jellyfin.tf and dual_gpu_passthrough role for patterns.

Backup Operations

# On backup container
restic snapshots
restic restore <snapshot-id> --target /​restore

Safety Protocols

Never Do

• Apply Terraform/​Ansible without dry-run first
• Skip user approval for any changes
• Edit terraform.tfstate manually
• Commit .tfstate files or unencrypted secrets
• Run apt, systemctl, or edit files via SSH (use IaC instead)
• Delete or modify infrastructure without understanding dependencies

Always Do

• Read current-state.md before making changes
• Present plan/​check output before applying
• Verify changes after applying (SSH, service status, logs)
• Commit changes including documentation updates
• Use SOPS/​Vault for secrets, never plaintext

Git Discipline

• Never skip pre-commit hooks
• Commit Terraform and Ansible changes separately
• Update current-state.md when infrastructure changes