diff --git a/docs/compose/traefik/traefik.toml b/docs/compose/traefik/traefik.toml index c09cf42a..7e09de58 100644 --- a/docs/compose/traefik/traefik.toml +++ b/docs/compose/traefik/traefik.toml @@ -28,6 +28,6 @@ entryPoint = "http" # This should include all of your mail domains, and main= should be your $TRAEFIK_DOMAIN [[acme.domains]] - main = "mail.your.doma.in" - sans = ["web.mail.your.doma.in", "smtp.mail.doma.in", "imap.mail.doma.in"] + main = "mail.example.com" + sans = ["web.mail.example.com", "smtp.mail.example.com", "imap.mail.example.com"] diff --git a/docs/reverse.rst b/docs/reverse.rst index 29f9e9e1..14a9154e 100644 --- a/docs/reverse.rst +++ b/docs/reverse.rst @@ -3,14 +3,13 @@ Using an external reverse proxy One of Mailu use cases is as part of a larger services platform, where maybe other Web services are available than Mailu Webmail and admin interface. -In such a configuration, one would usually run a frontend reverse proxy to serve all Web contents based on criteria like the requested hostname (virtual hosts) and/or the requested path. Mailu Web frontend is disabled in the default setup for security reasons, it is however expected that most users will enable it at some point. Also, due to Docker Compose configuration structure, it is impossible for us to make disabling the Web frontend completely available through a configuration variable. This guide was written to help users setup such an architecture. +In such a configuration, one would usually run a frontend reverse proxy to serve all Web contents based on criteria like the requested hostname (virtual hosts) and/or the requested path. Mailu Admin Web frontend is disabled in the default setup for security reasons, it is however expected that most users will enable it at some point. Also, due to Docker Compose configuration structure, it is impossible for us to make disabling the Web frontend completely available through a configuration variable. This guide was written to help users setup such an architecture. 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 +- `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`_ All options will require that you modify the ``docker-compose.yml`` file. @@ -89,7 +88,7 @@ Here is an example configuration : server { listen :443; - server_name yourpublicname.tld; + server_name external.example.com; # [...] here goes your standard configuration location /webmail { @@ -99,7 +98,7 @@ Here is an example configuration : server { listen :443; - server_name yourinternalname.tld; + server_name internal.example.com; # [...] here goes your standard configuration location /admin { @@ -113,7 +112,7 @@ Depending on how you access the front server, you might want to add a ``proxy_re .. code-block:: nginx - proxy_redirect https://localhost https://your-domain.com; + proxy_redirect https://localhost https://example.com; This will stop redirects (301 and 302) sent by the Webmail, nginx front and admin interface from sending you to ``localhost``. @@ -151,8 +150,8 @@ Add the respective Traefik labels for your domain/configuration, like .. 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``, +If your Traefik is configured to automatically request certificates from *letsencrypt*, then you’ll have a certificate for ``mail.your.example.com`` now. However, +``mail.your.example.com`` might only be the location where you want the Mailu web-interfaces to live — your mail should be sent/received from ``your.example.com``, and this is the ``DOMAIN`` in your ``.env``? To support that use-case, Traefik can request ``SANs`` for your domain. The configuration for this will depend on your Traefik version. @@ -171,12 +170,12 @@ Add the appropriate labels for your domain(s) to the ``front`` container in ``do # Enable TLS - "traefik.http.routers.mailu-secure.tls" # Your main domain - - "traefik.http.routers.mailu-secure.tls.domains[0].main=your.doma.in" + - "traefik.http.routers.mailu-secure.tls.domains[0].main=your.example.com" # Optional SANs for your main domain - - "traefik.http.routers.mailu-secure.tls.domains[0].sans=mail.your.doma.in,webmail.your.doma.in,smtp.your.doma.in" + - "traefik.http.routers.mailu-secure.tls.domains[0].sans=mail.your.example.com,webmail.your.example.com,smtp.your.example.com" # Optionally add other domains - - "traefik.http.routers.mailu-secure.tls.domains[1].main=mail.other.doma.in" - - "traefik.http.routers.mailu-secure.tls.domains[1].sans=mail2.other.doma.in,mail3.other.doma.in" + - "traefik.http.routers.mailu-secure.tls.domains[1].main=mail.other.example.com" + - "traefik.http.routers.mailu-secure.tls.domains[1].sans=mail2.other.example.com,mail3.other.example.com" # Your ACME certificate resolver - "traefik.http.routers.mailu-secure.tls.certResolver=foo" @@ -193,8 +192,8 @@ Lets add something like [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"] + main = "your.example.com" # this is the same as $TRAEFIK_DOMAIN! + sans = ["mail.your.example.com", "webmail.your.example.com", "smtp.your.example.com"] to your ``traefik.toml``. @@ -259,9 +258,7 @@ You can also download the example configuration files: - :download:`compose/traefik/docker-compose.yml` - :download:`compose/traefik/traefik.toml` -Disable completely Mailu reverse proxy --------------------------------------- +.. _have Mailu Web frontend listen locally and use your own Web frontend on top of it: #have-mailu-web-frontend-listen-locally +.. _use Traefik in another container as central system-reverse-proxy: #traefik-as-reverse-proxy +.. _override Mailu Web frontend configuration: #override-mailu-configuration -You must not disable Mailu reverse proxy by removing the ``front`` section from the ``docker-compose.yml``. - -``front`` is handling authentication and is also proxying e.g. SMTP and IMAP. A basic HTTP reverse proxy as described in this document is not sufficient for this.