You are currently browsing documentation for the master branch. Documentation for the stable 1.5 branch can be found here.

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:

mkdir /mailu
cd /mailu

Create the configuration files

Docker Compose configuration is stored in a file named docker-compose.yml. 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 certificates

Sets the TLS_FLAVOR to one of the following values:

  • cert is the default and requires certificates to be setup manually;
  • letsencrypt will use the Letsencrypt! CA to generate automatic ceriticates;
  • mail is similar to cert except that TLS will only be served for emails (IMAP and SMTP), not HTTP (use it behind reverse proxies);
  • mail-letsencrypt is similar to letsencrypt except that TLS will only be served for emails (IMAP and SMTP), not HTTP (use it behind reverse proxies);
  • notls will disable TLS, this is not recommended except for testing.


When using Letsencrypt! you have to make sure that the DNS A and AAAA records for the all hostnames mentioned in the HOSTNAMES variable match with the ip adresses of you server. Or else certificate generation will fail! See also: Setting up your DNS.

Bind address

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  netmask  broadcast
        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 and ::. Note that running is 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.

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 mailu.env file.

If you set TLS_FLAVOR to cert or mail then you must create a certs directory in your root path and setup a key-certificate pair there:

  • cert.pem contains the certificate (override with TLS_CERT_FILENAME),
  • key.pem contains the key pair (override with TLS_KEYPAIR_FILENAME).

Start Mailu

You may now start Mailu. Move the to the Mailu directory and run:

docker-compose up -d

Finally, you must create the initial admin user account:

docker-compose exec admin flask mailu admin me password

This will create a user named 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 POSTMASTER in your mailu.env exists, 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!