Maintain a Mailu server
Upgrading the mail server
First check upstream for changes in the docker-compose.yml or in the
.env files. Also, check CHANGELOG.md for changes that you
might not want to include.
Update your .env file to reflect the version that you wish to install (if
you are running stable or latest, you may skip this and proceed), then
simply pull the latest images and recreate the containers :
docker compose pull
docker compose down
docker compose up -d
Monitoring the mail server
Logs are managed by Docker directly. You can easily read your logs using:
docker compose logs
Docker is able to forward logs to multiple log engines. Read the following documentation for details: https://docs.docker.com/engine/admin/logging/overview/.
Managing of external Let’s Encrypt certificates
When you are not using the embedded letsencrypt option from Mailu,
you cannot make use of it’s symlink functionality in the letsencrypt/live directory.
You should take care that after every renewal new certificates are copied to /mailu/certs and
the nginx process in the front container is reloaded.
In the case of certbot you could write a script to be executed as deploy hook. Example:
#!/bin/sh
cp /etc/letsencrypt/live/domain.com/privkey.pem /mailu/certs/key.pem || exit 1
cp /etc/letsencrypt/live/domain.com/fullchain.pem /mailu/certs/cert.pem || exit 1
docker exec mailu_front_1 nginx -s reload
docker exec mailu_front_1 doveadm reload
And the certbot command you will use in crontab would look something like:
52 0,12 * * * root /usr/bin/certbot renew --deploy-hook /path/to/script.sh
Migrating an instance
The SMTP protocol has an embedded retry mechanism and multiple MX that can serve a single domain, so that most migration processes or maintenance processes do not require any specific care.
Mailu relies heavily on files for storing everything, which helps the migration process, that can be performed based on file synchronization.
The suggested migration process consists of setting up a new backup server that drops incoming emails (Mailu not started), synchronizing both servers, stopping the main server and launching the backup server. Then, the backup server is switched as a main MX and the old server is deleted.
Prepare your new server, copy your
docker-compose.yml,.envand basic configuration files to the server, so that it is ready to start configuration Mailu, do not start MailuSetup your DNS so that the backup server is an additional, deprioritized MX for the domain; this can be complex if you serve many domains, in which case you can simply accept that some remote MX will retry for a couple of minutes, skip this step
While your DNS TTL expires and your modification propagates, start rsyncing your Mailu directory (
data,dkim,mail, etc.) to the new server, repeat until there are only a couple files synchronizedStop Mailu on the old server and run a final
rsyncwhile no process is writing to the filesStart Mailu on the new server, and production should be back to normal
Set your new server as the main MX for your domains, if you did not set an additional MX, make sure you still change the
AandAAAArecord for your MX name.
Importing an external mailbox
For a filesystem Maildir import, stage the source in the previous flat layout and let the IMAP container migrate it. The migration reads each account’s UID and GID from Admin, so create the account before staging its mail. Keep a backup of the source until the import is verified.
Create the domain and mailbox in Admin. Do not log in to the new mailbox before importing; its new storage location should be empty. While IMAP is running, check the account identity and paths:
docker compose exec imap doveadm user alice@example.org
Confirm that
uidandgidare present and equal. The mailbox home should resolve to the new sharded layout.Stop Dovecot so no process is using the mailbox. Find the host-side source directory mounted at
/mailby theimapservice in your Compose file, then copy the contents of the external Maildir root into its legacy address directory. For example, if the host-side mount is/mailu/mailand the source Maildir is/backup/alice/Maildir:docker compose stop imap mkdir -p /mailu/mail/alice@example.org cp -a /backup/alice/Maildir/. /mailu/mail/alice@example.org/
The staged directory must contain the Maildir entries such as
cur/,new/andtmp/directly. Do not add anotherMaildir/level, and do not change the source files’ ownership; the migration applies the account’s UID/GID.Start the IMAP container and follow its logs:
docker compose up -d imap docker compose logs -f imap
Startup logs identify each migrated mailbox and report that the work may take a long time. The migration moves recognized Maildir control files, subscriptions, UIDVALIDITY state, personal Sieve scripts and IMAP metadata to their new locations. It fixes message size fields, drops rebuildable Dovecot and Xapian indexes, and leaves unrecognized legacy files in the staging directory for review. If startup is interrupted, start
imapagain; the operation resumes from the files already moved.Rebuilding Dovecot indexes, virtual message sizes and quotas runs after Dovecot starts, one mailbox at a time, and resumes from the remaining mailbox queue after an interruption. If full-text search is enabled, its indexes are rebuilt for the configured languages during the initial layout migration and whenever those settings change. Importing an additional mailbox rebuilds only that mailbox’s indexes. Ordinary restarts leave existing FTS indexes alone. A full rebuild can add substantial startup time. When attachment indexing is enabled, Tika must be available before the rebuild proceeds.
Verify the effective paths and ownership after the rebuild completes:
docker compose exec imap doveadm user alice@example.org docker compose exec imap doveadm mailbox path -u alice@example.org INBOX docker compose exec imap doveadm mailbox path -t index -u alice@example.org INBOX docker compose exec imap stat -c '%u:%g %n' /mail/example.org/hc/alice
Dovecot reports paths relative to its
/mailchroot, sodoveadm usershows/<domain>/<shard>/<localpart>; the corresponding container path is/mail/<domain>/<shard>/<localpart>. Mail is stored in itsmail/subdirectory, persistent indexes inindexes/, personal Sieve scripts insieve/, and IMAP metadata inmetadata/. The reported file owner must match the account’s UID/GID. Mailbox homes are created on the first delivery or authenticated mail session. Existing homes with unexpected ownership or permissions are not changed. The mailbox root and its domain and shard directories permit traversal but not directory listing.
This staging workflow also works after the initial mail-layout-v1 migration:
the IMAP startup script checks for recognized Maildirs under legacy
/mail/<email-address> paths on each start. Leave the layout marker in place;
removing it would unnecessarily rerun the migration and rebuild indexes for
every account. IMAP-to-IMAP transfers performed with a tool such as imapsync
can instead deliver directly through the new account and do not need this
filesystem staging procedure.