diff --git a/docs/convergence.md b/docs/convergence.md new file mode 100644 index 0000000..e57df5c --- /dev/null +++ b/docs/convergence.md @@ -0,0 +1,48 @@ +# 🔧 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 + +```bash +make converge +``` + +This will: +1. Decrypt secrets locally (with your age key) +2. Run the Ansible playbooks against all hosts in your `inventory/servers.yaml` +3. Apply the baseline security and tooling configuration + +## Verifying + +Once convergence completes, you can test: + +```bash +ssh admin@ + +# Check sudo access without password +sudo -n true && echo "✔ sudo OK" + +# Firewall status +sudo ufw status + +# Installed tools +htop --version +``` + +## 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.