# Runbook: Homelab managed updates with Ansible

## Purpose

Safely check and apply package updates to managed homelab guests using Ansible from the Nimrod LXC.

## Current MVP

- Execution host: Nimrod LXC `/home/piagent/projects/nimrod`
- Ansible config: `ansible/ansible.cfg`
- Inventory: `ansible/inventories/homelab/hosts.yml`
- First trial target: `homepage-dashboard` / CTID 107 / `192.168.0.241`
- MVP mode: manual only; no schedules or unattended critical updates.

## Update Classes

- `experimental`: low-risk/disposable/non-core services; eligible for first trials.
- `standard`: routine non-critical services after backup/snapshot expectations are defined.
- `critical_manual`: DNS, reverse proxy, Vaultwarden, Nimrod, Nextcloud; inspect and plan before updating.
- `manual_only`: Proxmox hosts/hypervisors, router/firewall changes, major upgrades, and data-destructive changes.

## Safety Rules

- No unattended/automatic critical updates in MVP.
- Do not run broad `all` upgrades.
- Use `--limit` and `target_update_class` gates.
- Verify snapshots/backups and service health before mutation.
- Do not reboot unless explicitly planned with `allow_reboot=true`.
- Log server-side update mutations in `docs/server-change-log.md`.

## Read-Only Preflight

Inventory:

```sh
cd /home/piagent/projects/nimrod
ansible-inventory -i ansible/inventories/homelab/hosts.yml --graph
```

Connectivity/facts for first trial:

```sh
ansible-playbook -i ansible/inventories/homelab/hosts.yml ansible/playbooks/preflight.yml --limit first_trial
```

Check pending updates without upgrading:

```sh
ansible-playbook -i ansible/inventories/homelab/hosts.yml ansible/playbooks/check-updates.yml --limit first_trial
```

## Apply Updates to First Trial Target

Only after preflight and service rollback are confirmed:

```sh
ansible-playbook -i ansible/inventories/homelab/hosts.yml \
  ansible/playbooks/apt-upgrade.yml \
  --limit first_trial \
  -e target_update_class=experimental
```

Default behavior:

- safe apt upgrade only
- no release upgrade
- no automatic reboot
- prints summary for change log

## Critical Manual Hosts

For `critical_manual` hosts, do not update unless there is an explicit maintenance plan.

If approved later, command shape is intentionally noisy:

```sh
ansible-playbook -i ansible/inventories/homelab/hosts.yml \
  ansible/playbooks/apt-upgrade.yml \
  --limit reverse-proxy \
  -e target_update_class=critical_manual \
  -e allow_critical_manual=true
```

## Verification

After updates:

- Rerun `check-updates.yml`.
- Verify service runbook health checks.
- Check whether reboot is required.
- Log changed host, commands, verification, reboot status, and rollback notes.

For Homepage first trial:

```sh
curl -sS -o /dev/null -w 'direct=%{http_code}\n' http://192.168.0.241:3000/
curl -k --resolve dashboard.dropcutstud.io:443:192.168.0.137 https://dashboard.dropcutstud.io/ -I
```

## Rollback / Recovery

- Use service runbook first.
- For Homepage, restart Docker/compose from `/opt/homepage`.
- If needed, revert Proxmox snapshot `post-homepage-dashboard-mvp` with explicit operator approval.
- Revert repo config changes with git if Ansible layout needs revision.

## Related Files

- Ticket: `tickets/active/2026-06-06-managed-update-schedules-ansible.md`
- Plan: `tickets/artifacts/2026-06-06-managed-update-schedules-ansible/05-plan.md`
- Inventory: `ansible/inventories/homelab/hosts.yml`
- Playbooks: `ansible/playbooks/`
- Change log: `docs/server-change-log.md`