# 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)

```bash
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.