diff --git a/docs/compose/treafik/docker-compose.yml b/docs/compose/traefik/docker-compose.yml similarity index 93% rename from docs/compose/treafik/docker-compose.yml rename to docs/compose/traefik/docker-compose.yml index 0dc8369f..607fcaf1 100644 --- a/docs/compose/treafik/docker-compose.yml +++ b/docs/compose/traefik/docker-compose.yml @@ -20,7 +20,7 @@ services: certdumper: restart: always - image: nebukadneza/traefik-certdumper:latest + image: mailu/traefik-certdumper:$VERSION 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! @@ -41,7 +41,6 @@ services: - "traefik.frontend.rule=Host:$TRAEFIK_DOMAIN" - "traefik.docker.network=mailu_default" ports: - - "80" # Let’s not expose 80 or 443 on host, since that’s taken by traefik - "$BIND_ADDRESS4:110:110" - "$BIND_ADDRESS4:143:143" - "$BIND_ADDRESS4:993:993" @@ -57,7 +56,6 @@ services: - "$BIND_ADDRESS6:465:465" - "$BIND_ADDRESS6:587:587" 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 diff --git a/docs/compose/treafik/traefik.toml b/docs/compose/traefik/traefik.toml similarity index 100% rename from docs/compose/treafik/traefik.toml rename to docs/compose/traefik/traefik.toml diff --git a/docs/reverse.rst b/docs/reverse.rst index cd23aad1..5f64b8f3 100644 --- a/docs/reverse.rst +++ b/docs/reverse.rst @@ -115,21 +115,28 @@ 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 +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. +`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`` 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. +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``. -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 +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 @@ -138,12 +145,14 @@ Next, in your ``docker-compose.yml``, comment out the ``port`` lines of the ``fr - "traefik.port=80" - "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``? -To support that use-case, ``traefik`` can request ``SANs`` for your domain. Lets add something like +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 +.. code-block:: guess [acme] [[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. -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: +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 certdumper: restart: always - image: nebukadneza/traefik-certdumper:latest + image: mailu/traefik-certdumper:$VERSION 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! @@ -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 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. +.. _`Traefik`: https://traefik.io/ 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: @@ -202,7 +212,10 @@ Then modify your ``docker-compose.yml`` file and change the ``front`` section to - "$ROOT/certs:/certs" - "$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: + +- :download:`compose/traefik/docker-compose.yml` +- :download:`compose/traefik/traefik.toml` Disable completely Mailu reverse proxy --------------------------------------