mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2025-08-21 03:05:02 +02:00
Kevin Veen-Birkenbach
3d7bbabd7b
- 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
91 lines
3.0 KiB
Markdown
91 lines
3.0 KiB
Markdown
# 📖 **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:
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
chown -R mail:mail /var/lib/docker/volumes/mailu_dovecot_mail/_data/kevinveenbirkenbach@infinito.nexus
|
||
```
|
||
|
||
---
|
||
|
||
### 5. Restart services and test login
|
||
|
||
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:
|
||
|
||
```bash
|
||
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.
|