boma/docs/decisions/003-toolchain.md

# ADR-003 — Toolchain decisions

## Status

Accepted (2026-05-30)

## Context

boma needs a defined, reproducible toolchain for running and testing its Ansible
monorepo: an execution engine, a Python environment, secrets handling, a testing
framework, linting, CI/CD, developer-ergonomics conventions, and a collections/roles
policy. This ADR records the choice made for each, together with the alternatives
weighed and why they were not adopted.

## Decision

### 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** (trunk-based — no pull requests; see CLAUDE.md git conventions):
1. Push to `main` → lint + Molecule tests
2. On green → deploy to staging
3. [manual promote gate] → deploy to production

`act_runner` runs as a Docker container on `ubongo` (the control node — ADR-015), or on
a dedicated runner VM later if CI load warrants a separate host.

---

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

## Consequences

Drawn from the rationale and trade-offs this ADR already states:

- Pinning `ansible-core` + an explicit `requirements.yml` and a plain pinned venv keeps
  the control-node environment small and fully reproducible, at the cost of maintaining
  the pins (per Execution engine / Python environment).
- Ansible Vault's whole-file encryption makes diffs unreadable regardless of layout, so
  secrets are organised for human lookup (`vault.<service>.<key>`) rather than diff
  ergonomics — the trade accepted against SOPS/age (per Secrets).
- The `Makefile` is the single interface: Claude Code and CI invoke the same targets, so
  local and CI behaviour can't drift and collaborators need not know raw flags (per
  Developer ergonomics).
- Collections are added only on demand, so `requirements.yml` stays minimal; this defers
  `community.crypto` (use `openssl` CLI until a role needs certs) and `community.general`
  (add only the specific sub-module needed) until a real need appears (per Collections
  and roles policy).
- The heavier orchestration tools were declined for this scale, each with a named
  revisit trigger — e.g. Semaphore if non-SSH operators must trigger runs, AWX-adjacent
  tooling only if AWX/AAP is ever adopted (per "What was explicitly ruled out").