Ansible homelab

Infrastructure automation for a Proxmox-based homelab running primarily Debian 13 VMs with Docker services. Stable, secure, and fully managed via Ansible.

Quick start (control node)

git clone <repo-url> ~/ansible
cd ~/ansible

# Create venv and install dependencies
make setup
make collections

# Place vault password (obtain via secure channel)
echo "your-vault-password" > .vault_pass
chmod 600 .vault_pass

# Verify setup
make lint

Common operations

What	Command
Lint everything	make lint
Dry-run site playbook	make check PLAYBOOK=site
Deploy everything	make deploy PLAYBOOK=site
Test a role	make test ROLE=base
Scaffold a new role	make new-role NAME=myservice

See Makefile for the full list of targets.

Project structure

.
├── CLAUDE.md               # Claude Code session context
├── Makefile                # All operations go through here
├── ansible.cfg             # Project-scoped Ansible config
├── requirements.txt        # Python dependencies
├── requirements.yml        # Ansible collections
│
├── docs/
│   ├── decisions/          # Architecture decision records (ADRs)
│   └── runbooks/           # Step-by-step operational procedures
│
├── inventories/
│   ├── production/         # Live hosts — edit carefully
│   └── staging/            # Test hosts — safe to run freely
│
├── playbooks/              # Orchestration playbooks
│   ├── site.yml            # Full standard state
│   └── bootstrap.yml       # First-run new host setup
│
├── roles/                  # Ansible roles
│   ├── base/               # OS baseline applied to all hosts
│   └── docker_host/        # Docker runtime setup
│
├── terraform/              # VM provisioning + infra DNS (see ADR-006/009)
│   ├── modules/            # Reusable modules (proxmox_vm)
│   └── environments/       # Per-env state: staging/, production/
│
└── scripts/                # Helper scripts (tf_to_inventory.py)

Documentation

• Current state (built vs planned): STATUS.md — read this before assuming something exists; the ADRs describe intent, not necessarily reality.
• AI agents: AGENTS.md (points to CLAUDE.md, the authoritative guide)
• Architecture: docs/decisions/001-architecture.md
• Security baseline: docs/decisions/002-security.md
• Toolchain decisions: docs/decisions/003-toolchain.md
• Docker model: docs/decisions/004-docker-model.md
• Bootstrapping: docs/decisions/005-bootstrapping.md
• Terraform: docs/decisions/006-terraform.md
• Network topology: docs/decisions/007-network.md
• Testing methodology: docs/decisions/008-testing.md
• Terraform ↔ Ansible handoff: docs/decisions/009-provisioning-handoff.md

Contributing

See CONTRIBUTING.md for conventions, branching strategy, and how to add roles.