From e128d8e975529485e7533766e43e93d1e4376bbc Mon Sep 17 00:00:00 2001 From: Dario Ernst Date: Wed, 5 Dec 2018 21:50:07 +0100 Subject: [PATCH] Add documentation for usage behind traefik --- docs/reverse.rst | 67 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/docs/reverse.rst b/docs/reverse.rst index ca68fd7f..cd23aad1 100644 --- a/docs/reverse.rst +++ b/docs/reverse.rst @@ -8,6 +8,7 @@ In such a configuration, one would usually run a frontend reverse proxy to serve There are basically three options, from the most to the least recommended one: - have Mailu Web frontend listen locally and use your own Web frontend on top of it +- use ``Traefik`` in another container as central system-reverse-proxy - override Mailu Web frontend configuration - disable Mailu Web frontend completely and use your own @@ -114,6 +115,72 @@ Depending on how you access the front server, you might want to add a ``proxy_re This will stop redirects (301 and 302) sent by the Webmail, nginx front and admin interface from sending you to ``localhost``. +use ``traefik`` in another container as central system-reverse-proxy +-------------------------------------------------------------------- + +``traefik`` is a popular reverse-proxy aimed at containerized systems. As such, many may wish to integrate ``Mailu`` into a system which already uses ``traefik`` as its sole ingress/reverse-proxy. + +As the ``mailu/front`` container uses ``nginx`` not only for ``HTTP`` forwarding, but also for the mail-protocols like ``SMTP``, ``IMAP``, etc, we need to keep this container around even when using another ``HTTP`` reverse-proxy. Furthermore, ``traefik`` is neither able to forward non-HTTP, nor can it easily forward HTTPS-to-HTTPS. This, however, means 3 things: + +- ``mailu/front`` needs to listen internally on ``HTTP`` rather than ``HTTPS`` +- ``mailu/front`` is not exposed to the outside world on ``HTTP`` +- ``mailu/front`` still needs ``SSL`` certificates (here, we assume ``letsencrypt``) for a well-behaved mail service + +This makes the setup with ``traefik`` a bit harder: ``traefik`` saves its certificates in a proprietary ``JSON`` file, which is not readable by the ``nginx`` in the ``front``-container. To solve this, your ``acme.json`` needs to be exposed to the host or a ``docker-volume``. It will then be read by a script in another container, which will dump the certificates as ``PEM`` files, making them readable for ``nginx``. The `front` container will make sure to reload `nginx` whenever these certificates change. + +To set this up, first set ``TLS_FLAVOR=mail`` in your ``.env``. This tells ``mailu/front`` not to try to request certificates using ``letsencrypt``, but to read provided certificates, and use them only for mail-protocols, not for ``HTTP``. +Next, in your ``docker-compose.yml``, comment out the ``port`` lines of the ``front`` section for port ``…:80`` and ``…:440``. Add the respective traefik labels for your domain/configuration, like + +.. code-block:: yaml + + labels: + - "traefik.enable=true" + - "traefik.port=80" + - "traefik.frontend.rule=Host:$TRAEFIK_DOMAIN" + +**Please don’t forget to add ``TRAEFIK_DOMAIN=[...]`` TO YOUR ``.env``** + +If your ``traefik`` is configured to automatically request certificates from ``letsencrypt``, then you’ll have a certificate for ``mail.your.doma.in`` now. However, ``mail.your.doma.in`` might only be the location where you want the ``Mailu`` web-interfaces to live — your mail should be sent/received from ``your.doma.in``, and this is the ``DOMAIN`` in your ``.env``? +To support that use-case, ``traefik`` can request ``SANs`` for your domain. Lets add something like + +.. code-block:: toml + + [acme] + [[acme.domains]] + main = "your.doma.in" # this is the same as $TRAEFIK_DOMAIN! + sans = ["mail.your.doma.in", "webmail.your.doma.in", "smtp.your.doma.in"] + +to your ``traefik.toml``. You might need to clear your ``acme.json``, if a certificate for one of these domains already exists. + +For the last part, you’re still a bit on your own. You need some solution which dumps the certificates in ``acme.json``, so you can include them in the ``mailu/front`` container. One such example is `traefik-certdumper `, which has been adapted for use in Mailu. You can add it to your ``docker-compose.yml`` like: + +.. code-block:: yaml + + certdumper: + restart: always + image: nebukadneza/traefik-certdumper:latest + environment: + # Make sure this is the same as the main=-domain in traefik.toml + # !!! Also don’t forget to add "TRAEFIK_DOMAIN=[...]" to your .env! + - DOMAIN=$TRAEFIK_DOMAIN + volumes: + - "/data/traefik:/traefik" + - "$ROOT/certs:/output" + + + +assuming you have ``volume-mounted`` your ``acme.json`` put to ``/data/traefik`` on your host. The dumper will then write out ``/data/traefik/ssl/your.doma.in.crt`` and ``/data/traefik/ssl/your.doma.in.key`` whenever ``acme.json`` is updated. Yay! Now let’s mount this to our ``front`` container like: + +.. code-block:: yaml + + volumes: + - "$ROOT/certs:/certs" # Mount both certs directory (for dhparams.pem) and your domains key + - "$ROOT/overrides/nginx:/overrides" + - /data/traefik/ssl/$TRAEFIK_DOMAIN.crt:/certs/cert.pem + - /data/traefik/ssl/$TRAEFIK_DOMAIN.key:/certs/key.pem + + +Note that we still keep the ``$ROOT/certs`` directory-mount there, where ``dhparams.pem`` is going to be placed. Override Mailu configuration ----------------------------