mailu/docs/compose/setup.rst

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:

.. code-block:: bash

  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.

.. _`mailu setup utility`: https://setup.mailu.io

.. _tls_flavor:

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 certificates;
- ``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.

.. note::

  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: :ref:`dns_setup`.

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:

.. code-block:: bash

  [root@mailu ~]$ ifconfig eth0
  eth0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
          inet 125.189.138.127  netmask 255.255.255.0  broadcast 5.189.138.255
          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 ``0.0.0.0`` and ``::``. Note that running is this mode is not supported and can lead to `issues`_.

.. _issues: https://github.com/Mailu/Mailu/issues/641

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 :ref:`common_cfg` 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:

.. code-block:: bash

  docker-compose up -d

Finally, you need an admin user account. 

You can have the system create it automatically:
use the environment variables ``INITIAL_ACCOUNT*`` as described in :ref:`admin_account`
You should set ``INITIAL_ADMIN_MODE`` also to either ``update`` or ``ifmissing``. Leaving it with the default value could cause errors when restarting the system.  

Else, if you don't go with the automatic way, you need to manually create the admin account now:

.. code-block:: bash

  docker-compose exec admin flask mailu admin me example.net 'password'

This will create a user named ``me@example.net`` with password ``password`` and administration privileges. Connect to the Web admin interface and change the password to a strong one.

  .. note:: 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!