# Runbook: routine operations through Ansible

Run commands from `ansible/`. The inventory forces IPv4 and uses the `windy`
account with sudo. Do a read-only health pass before any reconciliation.

## Health report (read-only)

```bash
cd ansible
ansible-playbook playbooks/health-report.yml
ansible-playbook playbooks/health-report.yml --limit mailcow
ansible-playbook playbooks/health-report.yml --limit matrix
```

This invokes the existing server-local checks and prints sanitized output; it
does not expose secrets or alter application configuration. A warning or
critical health result makes the play fail deliberately.

If the local health check has not been installed yet, deploy it first:

```bash
ansible-playbook playbooks/healthchecks.yml
ansible-playbook playbooks/matrix-healthchecks.yml
```

## Reconcile a known Compose service (mutating)

Only use this after a reviewed configuration change that requires a recreate.
The allowlist and flags are in inventory; arbitrary commands and service names
are rejected. Run one host at a time and re-run the health report afterwards.

```bash
# PowerDNS auth after its configuration changed
ansible-playbook playbooks/compose-reconcile.yml --limit powerdns \
  -e '{"service_reconcile_confirm": true, "service_reconcile_targets": ["auth"]}'

# Vaultwarden, including the documented Traefik refresh for a post-recreate 404
ansible-playbook playbooks/compose-reconcile.yml --limit vaultwarden \
  -e '{"service_reconcile_confirm": true, "service_reconcile_targets": ["vaultwarden"], "service_reconcile_restart_traefik": true}'

# Poweradmin after changing its environment or Traefik labels; restart its
# Traefik container only when the UI is returning 404
ansible-playbook playbooks/compose-reconcile.yml --limit powerdns \
  -e '{"service_reconcile_confirm": true, "service_reconcile_targets": ["poweradmin"], "service_reconcile_restart_traefik": true}'
```

Do not use this playbook for a Mailcow update, database migration, DNS record
change, or secret rotation. Those operations require their dedicated reviewed
and, where appropriate, interactive procedures.

## Host-level maintenance

These playbooks cover every inventory host, including the Matrix K3s node:

```bash
# Read-only pending package and reboot report
ansible-playbook playbooks/maintenance-preview.yml

# Baseline observations; logrotate management remains opt-in
ansible-playbook playbooks/baseline.yml
```