mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2025-08-20 18:55:01 +02:00

mailu: enable central database, improve token creation task, and add migration guide

- Enabled central_database in Mailu config
- Improved API token creation task:
  * use curl -f to fail on HTTP errors
  * added explicit failed_when and changed_when conditions
- Adjusted docker-compose template spacing for readability
- Made logging level configurable (DEBUG when MODE_DEBUG is set)
- Added new documentation Move_Domain.md explaining safe procedure for migrating mailboxes to a new domain

2025-08-18 01:03:40 +02:00

3.0 KiB

Raw Blame History

📖 How to Migrate Mailboxes to a New Domain in Mailu

When changing the primary email domain (e.g., from cymais.cloud to infinito.nexus), it is not enough to simply rename mailbox directories on disk. Mailu manages domain and user records in its internal database, and Dovecot maintains index files inside each Maildir. A blind rename will lead to login failures, rejected mail, or corrupted mail indices.

This guide explains the safe procedure for migrating user mailboxes to a new domain.

🔴 Why renaming folders directly does not work

Mailu keeps domains, users, and aliases in the admin_data database. If you rename folders only, Mailu will not recognize the new accounts.
Dovecot generates .dovecot.index* and dovecot-uidlist files in each mailbox. These must be rebuilt when moving mailboxes; otherwise, users may see missing or broken mail.
Postfix will refuse to deliver or relay messages for unknown domains.

✅ Correct migration procedure

1. Add the new domain and users in Mailu

Use the Mailu CLI inside the admin container:

# Add new domain
docker compose exec admin flask mailu domain add infinito.nexus

# Add new user (repeat for each account)
docker compose exec admin flask mailu user kevinveenbirkenbach infinito.nexus 'NEW_PASSWORD'

2. Copy or move existing Maildir contents

Instead of renaming, copy the entire Maildir from the old domain to the new one:

rsync -aHAX --numeric-ids \
  /var/lib/docker/volumes/mailu_dovecot_mail/_data/kevinveenbirkenbach@cymais.cloud/ \
  /var/lib/docker/volumes/mailu_dovecot_mail/_data/kevinveenbirkenbach@infinito.nexus/

3. Remove old Dovecot index files

Ensure that Dovecot rebuilds indices cleanly:

find /var/lib/docker/volumes/mailu_dovecot_mail/_data/kevinveenbirkenbach@infinito.nexus -type f -name '.dovecot*' -delete
find /var/lib/docker/volumes/mailu_dovecot_mail/_data/kevinveenbirkenbach@infinito.nexus -type f -name 'dovecot-uidlist*' -delete

4. Fix file permissions

Make sure all mailbox files belong to the mail:mail user/group:

chown -R mail:mail /var/lib/docker/volumes/mailu_dovecot_mail/_data/kevinveenbirkenbach@infinito.nexus

After copying, restart Mailu services (or at least imap and smtp) and confirm that users can log in with their new addresses.

6. (Optional) Keep the old domain as an alias

To ensure incoming mail for the old domain is still accepted:

docker compose exec admin flask mailu domain alias cymais.cloud infinito.nexus

This maps all @cymais.cloud addresses to their equivalents under @infinito.nexus.

💡 Summary

Do not just rename mailbox folders.
Always create the new domain and user in Mailu first.
Copy existing Maildir contents into the new user’s directory.
Remove Dovecot indices and fix permissions.
Optionally configure a domain alias so old addresses remain valid.

3.0 KiB Raw Blame History Unescape Escape