1958: Update the documentation on reverse proxies r=mergify[bot] a=nextgens

## What type of PR?

documentation

## What does this PR do?

Update the documentation on reverse proxies; this is mostly cosmetic (fix the links, use example.com where appropriate, ...).

It also removes the last option (run Mailu without its frontend) as that won't work with SSO and is a terrible idea anyway.

I wonder if we should just get rid of that section

### Related issue(s)
- #1528
- #1422
- #1038
- #1879

Co-authored-by: Florent Daigniere <nextgens@freenetproject.org>
master
bors[bot] 3 years ago committed by GitHub
commit 1d9850490c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -28,6 +28,6 @@ entryPoint = "http"
# This should include all of your mail domains, and main= should be your $TRAEFIK_DOMAIN # This should include all of your mail domains, and main= should be your $TRAEFIK_DOMAIN
[[acme.domains]] [[acme.domains]]
main = "mail.your.doma.in" main = "mail.example.com"
sans = ["web.mail.your.doma.in", "smtp.mail.doma.in", "imap.mail.doma.in"] sans = ["web.mail.example.com", "smtp.mail.example.com", "imap.mail.example.com"]

@ -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. 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: 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 - `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 - `use Traefik in another container as central system-reverse-proxy`_
- override Mailu Web frontend configuration - `override Mailu Web frontend configuration`_
- disable Mailu Web frontend completely and use your own
All options will require that you modify the ``docker-compose.yml`` file. All options will require that you modify the ``docker-compose.yml`` file.
@ -89,7 +88,7 @@ Here is an example configuration :
server { server {
listen <public_ip>:443; listen <public_ip>:443;
server_name yourpublicname.tld; server_name external.example.com;
# [...] here goes your standard configuration # [...] here goes your standard configuration
location /webmail { location /webmail {
@ -99,7 +98,7 @@ Here is an example configuration :
server { server {
listen <internal_ip>:443; listen <internal_ip>:443;
server_name yourinternalname.tld; server_name internal.example.com;
# [...] here goes your standard configuration # [...] here goes your standard configuration
location /admin { 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 .. 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``. 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 dont forget to add ``TRAEFIK_DOMAIN=[...]`` TO YOUR ``.env`` .. note:: Please dont forget to add ``TRAEFIK_DOMAIN=[...]`` TO YOUR ``.env``
If your Traefik is configured to automatically request certificates from *letsencrypt*, then youll have a certificate for ``mail.your.doma.in`` now. However, If your Traefik is configured to automatically request certificates from *letsencrypt*, then youll have a certificate for ``mail.your.example.com`` 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``, ``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``? 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. 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 # Enable TLS
- "traefik.http.routers.mailu-secure.tls" - "traefik.http.routers.mailu-secure.tls"
# Your main domain # 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 # 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 # 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].main=mail.other.example.com"
- "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].sans=mail2.other.example.com,mail3.other.example.com"
# Your ACME certificate resolver # Your ACME certificate resolver
- "traefik.http.routers.mailu-secure.tls.certResolver=foo" - "traefik.http.routers.mailu-secure.tls.certResolver=foo"
@ -193,8 +192,8 @@ Lets add something like
[acme] [acme]
[[acme.domains]] [[acme.domains]]
main = "your.doma.in" # this is the same as $TRAEFIK_DOMAIN! main = "your.example.com" # this is the same as $TRAEFIK_DOMAIN!
sans = ["mail.your.doma.in", "webmail.your.doma.in", "smtp.your.doma.in"] sans = ["mail.your.example.com", "webmail.your.example.com", "smtp.your.example.com"]
to your ``traefik.toml``. 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/docker-compose.yml`
- :download:`compose/traefik/traefik.toml` - :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.

Loading…
Cancel
Save