boma/docs/decisions/003-toolchain.md

ADR-003 — Toolchain decisions

Execution engine

Choice: ansible-core (pip-installed, pinned version) + explicit requirements.yml

Not chosen: ansible full package (bundles ~85 collections at a frozen version)

Rationale: Explicit collection pinning allows independent upgrades, smaller installs, and fully reproducible environments. The full package trades these away for convenience that isn't needed in a maintained monorepo.

---

Python environment

Choice: python3-venv (system Python on Debian 13) + pinned requirements.txt

Not chosen: pyenv (solves multi-version problems on developer laptops, not needed on a dedicated Debian control node with a controlled Python version)

Rationale: The control node runs one Python version. A plain venv is sufficient, reproducible, and has no extra dependencies.

---

Secrets

Choice: Ansible Vault (file-based, built-in)

Not chosen:

• SOPS + age: better git-diff ergonomics, but adds external tooling and key management
• HashiCorp Vault: powerful, but significant operational overhead for this scale

Rationale: Vault is built-in, requires no extra services, and works well at this scale. Whole-file encryption makes diffs unreadable regardless of layout, so rather than flattening we organise secrets for human lookup and clean extraction: a nested vault.<service>.<key> map inside each vault.yml, scoped to actual secrets (see CLAUDE.md → Secrets).

---

Testing

Choice: Molecule with Docker driver (molecule-plugins[docker])

Not chosen:

• Molecule + Podman: rootless is appealing, but Docker is simpler on a Debian control node
• Molecule + Vagrant: full VMs are slower and require a hypervisor on the control node
• No testing: unacceptable for a shared, maintained project

Test image: a self-built, project-owned Debian 13 image with systemd support (.docker/molecule-debian13/), hosted in the Forgejo registry. ADR-008 is canonical for the image and the rationale for not using an external image such as geerlingguy/docker-debian13-ansible.

Verifier: Built-in Ansible verifier. Testinfra added later if deeper assertions are needed.

---

Linting

Choice: ansible-lint + yamllint + pre-commit

• yamllint: catches formatting issues before Ansible sees the file
• ansible-lint: enforces correctness and idiomatic style
• pre-commit: runs both locally on every commit, preventing CI failures

Config files: .ansible-lint, .yamllint in repo root.

---

CI/CD

Choice: Forgejo Actions (self-hosted at forgejo.nyumbani.baobab.band) + act_runner

Not chosen: GitHub Actions (external), Jenkins (heavy)

Pipeline:

1. Push to any branch → lint + Molecule tests
2. Merge to main → lint + Molecule tests + manual approval gate
3. After approval → deploy to staging, then production

act_runner runs as a Docker container on the control node or a dedicated runner VM.

---

Developer ergonomics

Choice: Makefile as the single interface for all operations

Rationale: All ansible-playbook, molecule, and ansible-lint invocations go through Make targets. This means:

• Claude Code always calls make <target> — never constructs raw commands
• Collaborators don't need to know the underlying flags
• CI uses the same targets as local development (no drift)

direnv: Not used — the control node is a dedicated host, not a shared workstation. The venv is activated in the user's shell profile.

---

Collections and roles policy

No Galaxy roles. All roles are written and maintained locally in roles/. Galaxy roles introduce external state, versioning surprises, and implicit conventions that conflict with this repo's style.

Collections on demand. A collection is added to requirements.yml only when a task in a committed role actively uses a module from it. Pre-emptive inclusions are removed. Each entry in requirements.yml must justify its presence.

Starting collection set (rationale for each):

Collection	Kept / dropped	Reason
ansible.posix	Kept	Ansible-team maintained; fills real ansible.builtin gaps (authorized_key, sysctl, acl)
community.docker	Dropped	ADR-004 uses ansible.builtin.command + docker compose — no Docker API modules needed
community.proxmox	Dropped	Proxmox configuration is out of scope (ADR-001)
community.crypto	Deferred	Add when a role needs cert automation; use openssl CLI until then
community.general	Deferred	1,500+ modules; add only the specific sub-module needed, with a comment

---

What was explicitly ruled out

Tool	Reason not adopted
AWX / AAP	Significant operational overhead, not needed at this scale
Semaphore	Revisit if non-SSH operators need to trigger runs
ansible-runner	Only needed when AWX/Semaphore orchestrates runs
ansible-builder	Only needed when packaging Execution Environments for AWX
Kubernetes/Swarm	Out of scope — Docker Compose is the right complexity level
NixOS targets	Poor Ansible fit; all hosts standardised on Debian 13

Terraform is adopted for VM provisioning only (no DNS) — see docs/decisions/006-terraform.md.