first push with basic outline

README.md

@@ -0,0 +1,83 @@
+# VPS-ansible
+
+Ansible playbooks to provision and maintain a small fleet (~4) of VPSs.
+
+## Layout
+
+- `inventory.yml` - all hosts, grouped by role (`webservers`, `dbservers`, `misc`)
+- `group_vars/all/` - vars shared by every host (`vars.yml` plaintext, `vault.yml` encrypted secrets)
+- `group_vars/<group>.yml` or `group_vars/<group>/` - vars for one group of hosts
+- `host_vars/<hostname>.yml` - overrides unique to a single VPS
+- `roles/common` - baseline: packages, timezone, deploy user, unattended-upgrades
+- `roles/security` - SSH hardening, ufw, fail2ban
+- `roles/nginx`, `roles/docker`, `roles/postgres` - role-specific stacks, only applied to the relevant group
+- `site.yml` - top-level playbook: `common` + `security` run on `all`, then group-specific plays
+
+## First-time setup
+
+```bash
+ansible-galaxy collection install -r requirements.yml
+```
+
+Create your vault password file (gitignored, never commit it):
+
+```bash
+echo "your-vault-password" > .vault_pass
+chmod 600 .vault_pass
+```
+
+Encrypt the placeholder vault files before you fill in real secrets:
+
+```bash
+ansible-vault encrypt group_vars/all/vault.yml
+ansible-vault encrypt group_vars/dbservers/vault.yml
+```
+
+Edit an encrypted vault file (opens in VSCodium):
+
+```bash
+EDITOR="codium --wait" ansible-vault edit group_vars/all/vault.yml
+```
+
+Update `inventory.yml` with your real VPS IPs/hostnames, and
+`group_vars/all/vars.yml` with your real SSH public key(s).
+
+## Running
+
+Whole fleet:
+
+```bash
+ansible-playbook site.yml
+```
+
+Just one host:
+
+```bash
+ansible-playbook site.yml --limit vps1
+```
+
+Just one group:
+
+```bash
+ansible-playbook site.yml --limit webservers
+```
+
+Check mode (dry run) before applying anything for real:
+
+```bash
+ansible-playbook site.yml --check --diff
+```
+
+## Bootstrapping a brand-new VPS
+
+The `common` role assumes it can `become: true` (sudo) as `deploy_user`,
+which doesn't exist yet on a fresh VPS. For the very first run against a new
+box, connect as `root` (or whatever the provider gives you) and override the
+remote user on the command line:
+
+```bash
+ansible-playbook site.yml --limit vps1 -u root --ask-pass
+```
+
+After that first run creates `deploy_user` and installs your SSH key,
+subsequent runs will use `deploy_user` automatically via `ansible.cfg`.