ADR-001 — Architecture overview

Context

This document describes the overall architecture of the homelab infrastructure and the boundaries of what this Ansible monorepo manages.

Infrastructure

Hypervisor: Proxmox cluster (2+ nodes)
Guest OS: Debian 13 (all managed hosts)
Scale: 2–5 VMs, small fleet — treated as individuals, not cattle
Control node: ubongo — a dedicated always-on physical x86-64 machine outside the cluster. Ansible runs from here. It cannot be created by the Terraform it hosts, so it is provisioned manually (see ADR-015 and docs/runbooks/new-host.md).

What this repo manages

Layer	Managed by	Notes
VM existence	Terraform (`terraform/`)	Clones the cloud-init template; `ubongo` (control node) is a physical box outside the cluster, the one manual exception (see ADR-009/ADR-015)
Internal DNS records	Ansible `dns` role	Internal zone rendered from inventory (see ADR-007/009)
OS baseline	Ansible `base` role	Users, SSH, firewall, updates, audit
Docker runtime	Ansible `docker_host` role	Engine, daemon config, log driver
Service deployment	Ansible per-service roles	Compose rendered from templates
Secrets	Ansible Vault	Encrypted `vault.yml` files in repo

The Terraform↔Ansible boundary and handoff are defined in ADR-009. This table describes the intended design — see STATUS.md for what is actually built.

Host groups

all
├── control           # ubongo — physical control node outside the cluster; baseline config only, runs no services
├── docker_hosts      # VMs running Docker services (most hosts)
└── proxmox_hosts     # Proxmox nodes themselves (limited management scope)

The control group holds the single manually-provisioned control node; it is managed for baseline config (SSH, firewall, updates) but never runs the docker_host role. Proxmox nodes are managed only for basic baseline tasks (SSH). Proxmox configuration itself (storage, clustering, networking) is out of scope.

Service interaction model

Services run as Docker containers on one or more docker_hosts. Where services need to interact, they do so via:

Docker networks (same host)
Internal DNS / hostname resolution (cross-host)
Explicitly defined published ports (external access)

All Compose files are rendered by Ansible from Jinja2 templates. No hand-edited Compose files exist on hosts — they are always regenerated on deploy.

Decision

This architecture prioritises:

Simplicity: few moving parts, no orchestration layer (no Kubernetes, no Swarm)
Reproducibility: any host can be rebuilt from scratch via Ansible
Legibility: a human reading the repo can understand what runs where

2.9 KiB Raw Blame History Unescape Escape