feat: full untested ansible setup

README.md

@@ -1,3 +1,65 @@
 # Ansible Domo
 
-Ansible stuff for Twirre, by Twirre. Going for an Esperanto naming theme.
+Going for an Esperanto naming theme.
+
+Portable Ansible provisioning for Twirre infrastructure. The current layout is built around Debian-family hosts, `/srv` for deployed services, `/etc` for config, and systemd-managed apps.
+
+## What this provisions
+
+- Base host packages, timezone, and static content roots
+- SSH admin users with key-based login
+- A dedicated `backupagent` user for rsync-based backups with restricted SSH settings and passwordless `sudo /usr/bin/rsync`
+- Docker from distro packages
+- Bun installed to `/opt/bun` with `/usr/local/bin/bun`
+- Two Bun app services: `twirre.io` and `twirre.me`
+- Gitea and Docker Mailserver as Compose stacks under `/srv`
+- nginx virtual hosts for the retained public domains
+- apt-based certbot with ACME webroot support
+- WireGuard with `wg-quick@wg0` enabled at boot
+- fail2ban with the audit-derived SSH jail settings
+
+## Layout
+
+- `site.yml`: top-level playbook
+- `inventory/hosts.yml`: example inventory
+- `group_vars/all/main.yml`: shared variables and service declarations
+- `group_vars/all/vault.example.yml`: secrets shape to move into an encrypted Vault file
+- `roles/`: reusable server roles
+
+## Secrets
+
+Create an encrypted Vault file at `group_vars/all/vault.yml` based on `group_vars/all/vault.example.yml`. The playbook will use Vault variables when present and otherwise fall back to safe placeholders for syntax checking.
+
+Example:
+
+```bash
+ansible-vault create group_vars/all/vault.yml
+```
+
+## Usage
+
+Update the inventory and variables first, especially:
+
+- `inventory/hosts.yml`
+- `group_vars/all/main.yml`
+- `group_vars/all/vault.yml`
+- repository URLs and domains for the Bun apps
+- `backupagent.authorized_keys`
+
+Run a syntax check:
+
+```bash
+.venv/bin/ansible-playbook --syntax-check site.yml
+```
+
+Run the playbook:
+
+```bash
+.venv/bin/ansible-playbook site.yml
+```
+
+## Notes
+
+- nginx falls back to snakeoil certificates until a matching ACME certificate already exists on disk.
+- If you enable `certbot_manage_certificates`, run the playbook a second time after the first successful issuance so nginx can switch to the live certificates automatically.
+- ACME issuance is disabled by default through `certbot_manage_certificates: false` so the first provisioning run can complete before DNS and public reachability are finalized.