87 lines
3.1 KiB
Markdown
87 lines
3.1 KiB
Markdown
|
# 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.
|