# JOURNAL — phase mailu

Design rationale, dead-ends, investigation notes. Not for Adversary pre-verdict reading.

---

## 2026-06-11 Bootstrap + data-layout research

### mailu volume layout (from compose.yml analysis)

Services and their durable volumes:
- `admin` service: mounts `mailu` vol → `/data` (sqlite DB: users, mailboxes, domains, settings)
- `imap` (dovecot) service: mounts `mail` vol → `/mail` (Maildir message storage)
- `admin` service also mounts `dkim` vol → `/dkim` (DKIM private keys)
- `antispam` service: mounts `rspamd` vol → `/var/lib/rspamd` (antispam training data — ephemeral)
- `db` (redis) service: mounts `redis` vol → `/data` (session cache — ephemeral)
- `webmail` service: mounts `webmail` vol → `/data` (roundcube prefs — ephemeral)
- `smtp` service: mounts `mailqueue` vol → `/queue` (postfix queue — ephemeral)
- `app` (nginx) + `certdumper`: mount `certs` vol (TLS cert dumps — regenerable)

### Backup decision: admin/data + imap/mail

For genuine backup/restore coverage:
- **`admin:/data`** = sqlite DB → primary source of truth for mailboxes/users. If this is lost,
  all accounts are gone. Must backup.
- **`imap:/mail`** = Maildir storage → the actual messages. Loss = all mail gone. Must backup.
- `dkim:/dkim` = DKIM keys. In production, loss = need re-keying + DNS update. BUT: for CI testing,
  we don't have DNS-side DKIM records anyway, so DKIM regeneration is harmless. NOT labeled for
  CI simplicity (can add in a follow-up if operator wants DKIM key recovery tested).
- Other volumes: ephemeral / regenerable. Not labeled.

### Backupbot v2 syntax decision

From studying n8n and discourse examples:
- v2 uses `backupbot.backup: "true"` + `backupbot.backup.path: "<container-path>"`
- v1 used `backupbot.volumes.<name>=true/false` (immich pattern — do NOT use for new work)
- mailu has no Postgres (uses SQLite), so no pg_dump hook needed
- For `admin`: `backupbot.backup.path: "/data"` (whole sqlite DB dir)
- For `imap`: `backupbot.backup.path: "/mail"` (whole Maildir)

### mailu compose.yml structure note

mailu uses `deploy.labels` (list form with `- "key=value"` strings) for the app service's traefik labels. The backupbot labels need to go on the services that own the data:
- `admin` service uses `labels:` directly (not `deploy.labels`) — no traefik label there
- `imap` service similarly uses `labels:` directly

Wait, actually checking the compose.yml — there's no `labels:` on `admin` or `imap` at all. 
The `app` (nginx) service has `deploy.labels` for traefik. For backupbot, the labels need to be
on the DEPLOYED service (under `deploy.labels` or top-level `labels`). In Docker Swarm, backupbot
uses service labels (which are deploy-time labels). So we need `deploy.labels` on admin + imap.

The `app` service already uses `deploy.labels` (list form) for traefik. For admin + imap we need
to add `deploy:` → `labels:` sections.

### Version bump

Current version: `3.0.1+2024.06.52` (on `app` service `deploy.labels` → `coop-cloud.${STACK_NAME}.version`)
New version: `3.1.0+2024.06.52` (minor version bump for backupbot feature addition)

### CI test design

**ops.py hooks** (consistent with n8n pattern):
- `pre_backup(ctx)`: create a test mailbox `citest@<domain>` via `flask mailu user citest <domain> '<password>'` in the admin container
- `pre_restore(ctx)`: delete the mailbox via `flask mailu user delete citest@<domain>` (or equivalent) to simulate data loss

**test_backup.py**: assert `citest@<domain>` is in `config-export` at backup time

**test_restore.py**: assert `citest@<domain>` is back in `config-export` after restore

The `_mailu.py` helpers already provide:
- `flask_mailu(domain, cmd)` → runs flask mailu CLI in admin container
- `config_export(domain)` → parses config-export JSON
- `user_emails(cfg)` → list of email addresses from config

### Delete-user CLI for pre_restore

Need to confirm the delete command. From mailu docs, the admin CLI:
- Create: `flask mailu user <local> <domain> '<password>'`
- Delete: `flask mailu user delete <email>` (where email = local@domain)
- Or: `flask mailu user delete <local>@<domain>`
Need to verify the exact syntax. Will use `flask mailu user delete citest@<domain>` and add error handling.