- Removed code tages to increase readability
- Some extra line-breaks for source readability
- Fix link to new mailu/traefik-certdumper container
- dhparams is no longer stored in /certs
- Use a proper "note" box
- Fix typo in docs/compose/traefik directory name
- Include links to example config files
- Fix toml lexer build warning
``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.
`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:
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`` needs to listen internally on ``HTTP`` rather than ``HTTPS``
- ``mailu/front`` is not exposed to the outside world on ``HTTP``
- ``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
- ``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.
This makes the setup with Traefik a bit harder: Traefik saves its certificates in a proprietary *JSON* file, which is not readable by 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, readable for Nginx. The ``front`` container will automatically 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``.
To set this up, first set ``TLS_FLAVOR=mail`` in your ``.env``. This tells ``mailu/front`` not to try to request certificates using ``letsencrypt``,
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
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
..code-block:: yaml
@ -138,12 +145,14 @@ Next, in your ``docker-compose.yml``, comment out the ``port`` lines of the ``fr
- "traefik.port=80"
- "traefik.port=80"
- "traefik.frontend.rule=Host:$TRAEFIK_DOMAIN"
- "traefik.frontend.rule=Host:$TRAEFIK_DOMAIN"
**Please don’t forget to add ``TRAEFIK_DOMAIN=[...]`` TO YOUR ``.env``**
..note:: 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``?
If your Traefik is configured to automatically request certificates from *letsencrypt*, then you’ll have a certificate for ``mail.your.doma.in`` now. However,
To support that use-case, ``traefik`` can request ``SANs`` for your domain. Lets add something like
``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
..code-block::guess
[acme]
[acme]
[[acme.domains]]
[[acme.domains]]
@ -152,13 +161,14 @@ To support that use-case, ``traefik`` can request ``SANs`` for your domain. Lets
to your ``traefik.toml``. You might need to clear your ``acme.json``, if a certificate for one of these domains already exists.
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 <https://github.com/Nebukadneza/traefik-certdumper>`, which has been adapted for use in Mailu. You can add it to your ``docker-compose.yml`` like:
You will need some solution which dumps the certificates in ``acme.json``, so you can include them in the ``mailu/front`` container.
One such example is ``mailu/traefik-certdumper``, which has been adapted for use in Mailu. You can add it to your ``docker-compose.yml`` like:
..code-block:: yaml
..code-block:: yaml
certdumper:
certdumper:
restart: always
restart: always
image: nebukadneza/traefik-certdumper:latest
image: mailu/traefik-certdumper:$VERSION
environment:
environment:
# Make sure this is the same as the main=-domain in traefik.toml
# Make sure this is the same as the main=-domain in traefik.toml
# !!! Also don’t forget to add "TRAEFIK_DOMAIN=[...]" to your .env!
# !!! Also don’t forget to add "TRAEFIK_DOMAIN=[...]" to your .env!
@ -169,23 +179,23 @@ For the last part, you’re still a bit on your own. You need some solution whic
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:
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
..code-block:: yaml
volumes:
volumes:
- "$ROOT/certs:/certs" # Mount both certs directory (for dhparams.pem) and your domains key
Note that we still keep the ``$ROOT/certs`` directory-mount there, where ``dhparams.pem`` is going to be placed.
Override Mailu configuration
Override Mailu configuration
----------------------------
----------------------------
If you do not have the resources for running a separate reverse proxy, you could override Mailu reverse proxy configuration by using a Docker volume. Simply store your configuration file (Nginx format), in ``/mailu/nginx.conf`` for instance.
If you do not have the resources for running a separate reverse proxy, you could override Mailu reverse proxy configuration by using a Docker volume.
Simply store your configuration file (Nginx format), in ``/mailu/nginx.conf`` for instance.
Then modify your ``docker-compose.yml`` file and change the ``front`` section to add a mount:
Then modify your ``docker-compose.yml`` file and change the ``front`` section to add a mount:
@ -202,7 +212,10 @@ Then modify your ``docker-compose.yml`` file and change the ``front`` section to
- "$ROOT/certs:/certs"
- "$ROOT/certs:/certs"
- "$ROOT/nginx.conf:/etc/nginx/nginx.conf"
- "$ROOT/nginx.conf:/etc/nginx/nginx.conf"
You can use our default configuration file as a sane base for your configuration.
You can also download the example configuration files:
Tim Möhlmann
6 years ago