Files

tegwick b32dfd4f5a docs: add verification guide, close WP-0002

- docs/verification.md: explains spec/server-baseline.yaml, goss/baseline.yaml,
  make verify workflow, assertion mapping table, and how to add new checks
- docs/convergence.md: replace manual spot-check snippet with make verify reference
- workplans/RAIL-HO-WP-0002: mark completed (all tasks done, workstream closed)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-09 19:37:10 +01:00

1.6 KiB

Raw Blame History

🔧 Server Convergence

After provisioning servers with Terraform, RailianceHosts uses Ansible to bring them into a secure and usable baseline state.
This process is called convergence.

What Convergence Does

When you run make converge, Ansible connects to all declared hosts and applies baseline roles:

User setup → ensures the admin user exists with your SSH key and passwordless sudo
Firewall → configures ufw with sensible defaults (deny incoming, allow SSH)
Hardening → basic SSH daemon hardening, disable root login, disable password auth
Tooling → installs essential packages (htop, vim, git, curl, fail2ban, etc.)
SOPS agent → ensures decryption tooling (age, sops) is available on the host

Running Convergence

make converge

This will:

Decrypt secrets locally (with your age key)
Run the Ansible playbooks against all hosts in your inventory/servers.yaml
Apply the baseline security and tooling configuration

Verifying

After convergence, run the automated test suite to assert the node matches the baseline spec:

make verify

This runs Goss assertions against all hosts and exits non-zero on failure. TAP reports are written to reports/. See docs/verification.md for details.

For a quick human-readable summary without assertions:

make status

Notes

Convergence is idempotent: re-running it will not break your server.
Only your workstation (control node) needs the age private key; hosts never see it.
Additional roles (e.g. WireGuard, Kubernetes, apps) can be layered later.

1.6 KiB Raw Blame History