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

ansible-galaxy collection install -r requirements.yml

Create your vault password file (gitignored, never commit it):

echo "your-vault-password" > .vault_pass
chmod 600 .vault_pass

Encrypt the placeholder vault files before you fill in real secrets:

ansible-vault encrypt group_vars/all/vault.yml
ansible-vault encrypt group_vars/dbservers/vault.yml

Edit an encrypted vault file (opens in VSCodium):

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:

ansible-playbook site.yml

Just one host:

ansible-playbook site.yml --limit vps1

Just one group:

ansible-playbook site.yml --limit webservers

Check mode (dry run) before applying anything for real:

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:

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.