Merge #3440

3440: Update reverse proxy documentation for using Traefik on a different host r=mergify[bot] a=Diman0

## What type of PR?

documentation

## What does this PR do?

It adds an extra section to the reverse proxy documentation. It provides an example on how to use Traefik on a different host than the host running Mailu. Now we will have documented both use cases where the reverse proxy is on the same host or a different host than Mailu.

### Related issue(s)
n/a

## Prerequisites
Before we can consider review and merge, please make sure the following list is done and checked.
If an entry in not applicable, you can check it or remove it from the list.

- [x] In case of feature or enhancement: documentation updated accordingly
- [x] Unless it's docs or a minor change: add [changelog](https://mailu.io/master/contributors/workflow.html#changelog) entry file.


Co-authored-by: Dimitri Huisman <diman@huisman.xyz>

docs/reverse.rst

@@ -7,10 +7,31 @@ other Web services are available on other FQDNs served from the same IP address.
 In such a configuration, one would usually run a front-end reverse proxy to serve all
 Web contents based on criteria like the requested hostname (virtual hosts).
 
+The Mailu team recommends to use Traefik as reverse proxy. This program is solely designed
+to act as reverse proxy. It is easy to configure and offers a streamlined experienced when
+used with other docker containers on the same host.
+
+When using a reverse proxy, Mailu should still be used for requesting certificates.
+This prevents duplicate certificates.
+Other reasons are:
+
+- Mailu controls the ciphers and keys used for certificates (Mailu has both RSA and ECDSA certs)
+- Mailu cerbot client is configured to prevent hitting ratelimits of the CA
+- Due to usage of proxy protocol it is less likely that Mailu becomes an open relay due to misconfiguration of special headers.
+- No special scripting is required to copy over certs from the proxy to Mailu
+
+When using Mailu with Traefik as reverse proxy. Traefik is configured to use proxy protocol for all ports, but port 80.
+Port 80 is configured to let through the letsencrypt HTTP challenges for Mailu.
+This means that if Traefik must request certificates for other services than Mailu, Traefik should use the TLS (TLS-ALPN-01)
+challenge method. The HTTP challenge (HTTP-01) cannot be used since this is already used by Mailu.
+
 .. _traefik_proxy:
 
-Traefik as reverse proxy
-------------------------
+Traefik as reverse proxy (same host)
+------------------------------------
+
+This example is for when Traefik (reverse proxy) runs on the same host as Mailu.
+It makes use of the docker configuration method for Traefik.
 
 In your docker-compose.yml, remove the `ports` section of the `front` container
 and add a section like follows:
@@ -102,7 +123,7 @@ and then add the following to the front section:
 
 in mailu.env:
 
-.. code-block:: docker
+.. code-block:: bash
 
   REAL_IP_FROM=192.168.203.0/24
   PROXY_PROTOCOL=25,443,465,993,995,4190
@@ -111,3 +132,164 @@ in mailu.env:
   WEBROOT_REDIRECT=/sso/login
 
 Using the above configuration, Traefik will proxy all the traffic related to Mailu's FQDNs without requiring duplicate certificates.
+
+
+Traefik as reverse proxy (different host)
+-----------------------------------------
+
+This example is for when Traefik (reverse proxy) runs on a different server than the Mailu server.
+This example makes use of the File configuration method (File Provider) of Traefik.
+It makes use of a single static configuration file and one or more dynamic configuration files.
+
+This example uses V3 of Traefik. V2 and V3 of Traefik have some differences in the configuration method.
+
+The contents for the static configuration file. The static configuration file must be provided as argument to Traefik.
+
+.. code-block:: yaml
+
+  #STATIC CONFIGURATION FILE
+  #Below value for 'directory' is the location where the dynamic configuration files reside:
+  #When a change is made in this folder, Traefik automatically loads or reloads it.
+  providers:
+    file:
+      directory: "/etc/traefik/conf"
+
+  entryPoints:
+    web:
+      address: :80
+    websecure:
+      address: :443
+    mailu-smtp:
+      address: :25
+    mailu-imaps:
+      address: :993
+    mailu-pop3s:
+      address: :995
+    mailu-submissions:
+      address: :465
+    mailu-sieve:
+      address: :4190
+
+  #Optional, enables access logging at:
+  accessLog:
+    filePath: "/var/log/traefik_access.log"
+
+  #Optional, enables normal logging at:
+  log:
+    level: INFO
+    filePath: "/var/log/traefik.log"
+
+
+This is the contents for the dynamic configuration. You can use any filename you want.
+The extension must end with .yml and the file must be placed in the configured directory for
+dynamic configuration files.
+
+
+.. code-block:: yaml
+
+  http:
+    routers:
+      mailu-web:
+        entryPoints:
+          - web
+        rule: "Host(`mail.example.com) || PathPrefix(`/.well-known/acme-challenge/`))"
+        service: "mailu-web"
+    services:
+      mailu-web:
+        loadBalancer:
+          servers:
+            - url: "http://mailu-server"
+
+  tcp:
+    routers:
+      mailu-websecure:
+        entryPoints:
+          - websecure
+        # Add other FQDN's here
+        rule: "HostSNI(`mail.example.com`) || HostSNI(`autoconfig.example.com`) || HostSNI(`mta-sts.example.com`)"
+        service: "mailu-websecure"
+        tls:
+          passthrough: true
+      mailu-submissions:
+        entryPoints:
+          - mailu-submissions
+        rule: "HostSNI(`*`)"
+        service: "mailu-submissions"
+      mailu-imaps:
+        entryPoints:
+          - mailu-imaps
+        rule: "HostSNI(`*`)"
+        service: "mailu-imaps"
+        tls:
+          passthrough: true
+      mailu-pop3s:
+        entryPoints:
+          - mailu-pop3s
+        rule: "HostSNI(`*`)"
+        service: "mailu-pop3s"
+        tls:
+          passthrough: true
+      mailu-submissions:
+        entryPoints:
+          - mailu-submissions
+        rule: "HostSNI(`*`)"
+        service: "mailu-submissions"
+        tls:
+          passthrough: true
+      mailu-sieve:
+        entryPoints:
+          - mailu-sieve
+        rule: "HostSNI(`*`)"
+        service: "mailu-sieve"
+    services:
+      mailu-websecure:
+        loadBalancer:
+          proxyProtocol:
+            version: 2
+          servers:
+            - address: "mailu-server:443"
+      mailu-smtp:
+        loadBalancer:
+          proxyProtocol:
+            version: 2
+          servers:
+            - address: "mailu-server:25"
+      mailu-submissions:
+        loadBalancer:
+          proxyProtocol:
+            version: 2
+          servers:
+            - address: "mailu-server:465"
+      mailu-imaps:
+        loadBalancer:
+          proxyProtocol:
+            version: 2
+          servers:
+            - address: "mailu-server:993"
+      mailu-pop3s:
+        loadBalancer:
+          proxyProtocol:
+            version: 2
+          servers:
+            - address: "mailu-server:995"
+      mailu-sieve:
+        loadBalancer:
+          proxyProtocol:
+            version: 2
+          servers:
+            - address: "mailu-server:4190"
+
+
+In the mailu.env file add the following:
+
+
+.. code-block:: bash
+
+  #Add the IP address of the Traefik server as value for REAL_IP_FROM
+  REAL_IP_FROM=192.168.2.300/32
+  PROXY_PROTOCOL=25,443,465,993,995,4190
+  TLS_FLAVOR=letsencrypt
+  WEBROOT_REDIRECT=/sso/login
+
+
+Using the above configuration, Traefik will proxy all the traffic related to Mailu's FQDNs without requiring duplicate certificates.

towncrier/newsfragments/3440.doc

@@ -0,0 +1 @@
+The reverse proxy documentation page is updated with the scenario where Traefik (the reverse proxy) resides on a different server.