Docker Compose setup
Prepare the environment
Mailu will store all of its persistent data in a path of your choice
/mailu by default) simply create the directory and move there:
Create the configuration files
Docker Compose configuration is stored in a file named
Additionally, Mailu relies on a
mailu.env file for various settings.
Both files can be generated by the mailu setup utility. The setup utility
is mostly self-explanatory, with some more additional information in this section.
TLS_FLAVOR to one of the following
certis the default and requires certificates to be setup manually;
letsencryptwill use the Letsencrypt! CA to generate automatic certificates;
certexcept that TLS will only be served for emails (IMAP and SMTP), not HTTP (use it behind reverse proxies);
mail-letsencryptis similar to
letsencryptexcept that TLS will only be served for emails (IMAP and SMTP), not HTTP (use it behind reverse proxies);
notlswill disable TLS, this is not recommended except for testing.
When using Letsencrypt! you have to make sure that the DNS
AAAA records for the
all hostnames mentioned in the
HOSTNAMES variable match with the ip addresses of you server.
Or else certificate generation will fail! See also: Setting up your DNS.
The bind addresses need to match the public IP addresses assigned to your server. For IPv6 you will need the
<global> scope address.
You can find those addresses by running the following:
[root@mailu ~]$ ifconfig eth0
eth0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
inet 22.214.171.124 netmask 255.255.255.0 broadcast 126.96.36.199
inet6 fd21:aab2:717c:cc5a::1 prefixlen 64 scopeid 0x0<global>
inet6 fe2f:2a73:43a8:7a1b::1 prefixlen 64 scopeid 0x20<link>
ether 00:50:56:3c:b2:23 txqueuelen 1000 (Ethernet)
RX packets 174866612 bytes 127773819607 (118.9 GiB)
RX errors 0 dropped 0 overruns 0 frame 0
TX packets 19905110 bytes 2191519656 (2.0 GiB)
TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
If the address is not configured directly (NAT) on any of the network interfaces or if
you would simply like the server to listen on all interfaces, use
Note that running in this mode is not supported and can lead to issues.
Review configuration variables
After downloading the files, open
mailu.env and review the variable settings.
Make sure to read the comments in the file and instructions from the Common configuration page.
If your CPU supports Advanced Vector Extensions (AVX2 on x86_64, lrcpc on ARM64), you should consider enabling hardened-malloc earlier in the boot process by adding the following to your mailu.env:
Finish setting up TLS
Mailu relies heavily on TLS and must have a key pair and a certificate
available, at least for the hostname configured in the
If you set
in your root path and setup a key-certificate pair there:
cert.pemcontains the certificate (override with
key.pemcontains the key pair (override with
You may now start Mailu. Move the to the Mailu directory and run:
docker compose up -d
Finally, you need an admin user account.
You can have the system create it automatically:
use the environment variables
INITIAL_ADMIN_* as described in Admin account - automatic creation
Else, if you don’t go with the automatic way, you need to manually create the admin account now:
docker compose exec admin flask mailu admin me example.net 'password'
This will create a user named
firstname.lastname@example.org with password
password and administration privileges.
Connect to the Web admin interface and change the password to a strong one.
It is vitally important that either a user with the same email as
mailu.envexists, or you remember to create an alias with this name after you log in. All kinds of strange errors will occur as a result of not doing so!