windyboy
b0c01b2551
- RUNBOOKS.md: repo-level spec (six-field model, naming, safety, maturity path) - runbooks/_template.md + README.md: standard template and 16-entry routing index - new: issue-to-merge, fix-ci, release, rollback, network-change, network-recovery - light-enhance 10 existing runbooks with Purpose/Scope/Safety headers - AGENTS.md: point step 3 at index/spec, add runbook execution rules - docs/agent-runbook-guide.md: archive of Manus AI guide
67 lines
2.3 KiB
Markdown
67 lines
2.3 KiB
Markdown
# Runbook: mailcow update (mx2)
|
|
|
|
## Purpose
|
|
|
|
Update the mailcow stack on mx2 to the latest supported release.
|
|
|
|
## Scope
|
|
|
|
- Applicable: [mx2.windy.me](../hosts/mx2.windy.me.md), `/opt/mail`.
|
|
- Not applicable: config changes beyond the update, DB migration, secret rotation.
|
|
|
|
## Approval gates
|
|
|
|
| Action | Risk | Explicit approval |
|
|
|---|---|---|
|
|
| Run `./update.sh` (recreates containers, brief mail interruption) | Medium | Yes — user confirmation required |
|
|
|
|
Target: [mx2.windy.me](../hosts/mx2.windy.me.md)
|
|
Path: `/opt/mail`
|
|
**Confirm with the user before running an update.**
|
|
|
|
## Safety
|
|
|
|
- Never run the update without explicit user confirmation.
|
|
- Never pass secrets into the chat log; do not commit `mailcow.conf`.
|
|
- If a step fails, capture `docker compose ps` and logs and stop before further changes.
|
|
|
|
## Before
|
|
|
|
1. Run [mailcow-health](mailcow-health.md) (Ansible health report). Record baseline.
|
|
2. Note config quirks in `mailcow.conf`, especially:
|
|
- `SKIP_CLAMD=y` — after update, `clamd` may still be running until services are recreated per mailcow docs.
|
|
- `SKIP_LETS_ENCRYPT`, ports, hostname — should stay `mx2.windy.me`.
|
|
3. Disk/memory: `df -h /` and `free -h` on the host.
|
|
|
|
## Update
|
|
|
|
```bash
|
|
ssh -t windy@mx2.windy.me 'cd /opt/mail && ./update.sh'
|
|
```
|
|
|
|
- Prefer interactive SSH (`-t`) so prompts work.
|
|
- Do not pass secrets into the chat log; do not commit `mailcow.conf`.
|
|
|
|
If update asks to stop/recreate containers, allow it unless the user said otherwise.
|
|
|
|
## After
|
|
|
|
1. Re-run health checks ([mailcow-health](mailcow-health.md)).
|
|
2. Confirm UI: `https://mx2.windy.me`
|
|
3. Confirm SMTP banner and queue empty.
|
|
4. If `SKIP_CLAMD=y` but `cow-clamd-mailcow-1` is still Up and that is unwanted:
|
|
|
|
```bash
|
|
cd ansible
|
|
ansible-playbook playbooks/compose-reconcile.yml --limit mailcow \
|
|
-e '{"service_reconcile_confirm": true, "service_reconcile_targets": ["all"]}'
|
|
```
|
|
|
|
Only after user OK; recreate briefly interrupts mail.
|
|
|
|
5. Update **Verified** on [hosts/mx2.windy.me.md](../hosts/mx2.windy.me.md) with date and outcome.
|
|
|
|
## Rollback
|
|
|
|
Mailcow updates are image/git based; there is no one-click rollback in this runbook. If something fails, capture `docker compose ps` and `docker compose logs --tail=100` for the failing service and stop before further changes.
|