# 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`.