# Ansible

`site.yaml` is the desired state of asxpio-ops and is applied by the
deploy pipeline on every push to `main`. asxpio-services runs NixOS and
is described in `../nixos`. The playbooks under
`playbooks/` are host bootstrap and are run by hand.

## Running

```sh
echo '<vault password>' > .vault_pass && chmod 600 .vault_pass

ansible-playbook site.yaml --check --diff       # dry run, over WireGuard
ansible-playbook site.yaml                      # apply
ansible-playbook site.yaml --tags forgejo       # one role
```

On NixOS: `nix shell nixpkgs#ansible -c ansible-playbook …`.

Templates that carry secrets are never shown in `--diff` output.

## Inventories

- `inventory/hosts.yaml`: default. Connects as root to the WireGuard
  addresses.
- `inventory/ci.yaml`: used by the pipeline. Connects as `deploy` over
  the private network.

`known_hosts` pins both servers' SSH host keys for the pipelines (the
NixOS one uses it too).

## Variables

```
inventory/
├── group_vars/all/
│   ├── network.yaml         # VPC and WireGuard addresses
│   ├── paths.yaml           # /opt
│   ├── wireguard.yaml       # WireGuard peers
│   └── vault.yaml           # encrypted secrets
├── group_vars/ops_servers/
│   ├── traefik.yaml         # traefik_version
│   └── forgejo.yaml         # forgejo_version, domain and aliases
└── host_vars/               # per-host addresses and SSH settings
```

Compose files without variables are plain files under
`roles/<role>/files/`; edit the image tag there.

## Roles in site.yaml

`base`, `traefik`, `crawler_alert`, `forgejo`. Service roles go
through `docker_service`, which writes the files, runs
`docker compose up -d`, restarts on a config change and waits for the
service to answer.

`crawler_alert` installs a copy of
[traefik-crawlers-statistics](https://git.asxp.io/asxpi/traefik-crawlers-statistics);
update `roles/crawler_alert/files/` from there.

## Bootstrap playbooks

| Playbook | Purpose |
|----------|---------|
| `01-wireguard-setup.yaml` | WireGuard hub on asxpio-ops, client configs |
| `02-ssh-hardening.yaml` | restrict SSH to WireGuard and the private network |
| `04-add-user-zerrtika.yaml` | add a user to running servers |
| `05-swap.yaml` | 2 GB swapfile on asxpio-ops |

Always dry-run these first with `--check --diff`.

`/etc/s3fs/.passwd-s3fs` on asxpio-ops is a leftover of the removed s3fs
role and is still read by the backup script there; nothing manages it.