cc-ci/machine-docs/JOURNAL-mailu.md

JOURNAL — phase mailu

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

---

2026-06-11 ADV-mailu-01 fix — build #477 LEVEL 5 re-verified

ADV-mailu-01 resolution confirmed

Build #477 result confirms both volumes are now specifically tested:

• test_backup_captures_mail_message PASS: ccci-backup-probe message in INBOX at backup time
• test_restore_returns_mail_message PASS: message survives Maildir wipe + restore from snapshot
• Both maildir-specific tests ran in the backup and restore stages respectively
• Full build level 5, clean_teardown=true, no_secret_leak=true

The sendmail delivery path (smtp container → postfix → dovecot deliver) worked correctly for injecting the test message. The doveadm search poll with 60s timeout was sufficient. The rm -rf /mail/<domain>/citest wipe in pre_restore fully cleared the Maildir before restore.

Re-claiming M1 with build #477 as the evidence build.

---

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.

---

2026-06-11 ADV-mailu-01 fix — extend seed to cover /mail Maildir

Adversary finding (M1 FAIL)

The M1 claim was rejected because ops.py only proved SQLite (/data) backup/restore. The /mail Maildir volume was labeled and backed up but never specifically tested for restoration. If backupbot silently skipped restoring /mail, the test would still PASS.

Fix (cc-ci commit b9352e8)

Extended the seed in three steps:

ops.py pre_backup: After creating citest@<domain>, inject a test message via in-container sendmail (smtp container → postfix → rspamd → dovecot deliver). Subject: ccci-backup-probe. Wait up to 60s for dovecot to deliver (polling doveadm search). This is identical to the pattern proven in test_mail_flow.py.

ops.py pre_restore: Now wipes BOTH:

1. The user from sqlite: DELETE FROM user WHERE localpart='citest' via python3 in admin container
2. The user's Maildir: rm -rf /mail/<domain>/citest in imap container

test_backup.py: Added test_backup_captures_mail_message — asserts the message is present at backup time via doveadm search in imap container.

test_restore.py: Added test_restore_returns_mail_message — asserts the message is back in INBOX after restore via doveadm search in imap container.

Why rm -rf over doveadm expunge

Used rm -rf /mail/<domain>/citest/ in pre_restore rather than doveadm expunge because:

• rm -rf directly wipes the Maildir from disk — observable, immediate, unambiguous
• doveadm expunge marks messages for deletion but depends on dovecot's expunge/purge cycle
• The goal is a clear divergence: after pre_restore, the maildir DOES NOT EXIST; after restore, it DOES

Build #477 in flight to verify