We now use mailcows built-in ACME client in RP example setups

docs/firststeps-rp.md

@@ -1,5 +1,5 @@
 You don't need to change the Nginx site that comes with mailcow: dockerized.
-mailcow: dockerized trusts the default gateway IP 172.22.1.1 as proxy. This is very important to control access to Rspamd's web UI.
+mailcow: dockerized trusts the default gateway IP 172.22.1.1 as proxy.
 
 1\. Make sure you change HTTP_BIND and HTTPS_BIND in `mailcow.conf` to a local address and set the ports accordingly, for example:
 ``` bash
@@ -8,66 +8,103 @@ HTTP_PORT=8080
 HTTPS_BIND=127.0.0.1
 HTTPS_PORT=8443
 ```
-** IMPORTANT: Do not use port 8081 **
+**IMPORTANT:** Do not use port 8081!
 
 Recreate affected containers by running `docker-compose up -d`.
 
+!!! warning
+    Make sure you run `generate_config.sh` before you enable any site configuration examples below.
+    The script `generate_config.sh` copies snake-oil certificates to the correct location, so the services will not fail to start due to missing files.
+
+!!! info
+    Using the site configs below will **forward ACME requests to mailcow** and let it handle certificates itself.
+    The downside of using mailcow as ACME client behind a reverse proxy is, that you will need to reload Apache after the certificate changed. You can either reload Apache daily or write a script to watch the file for changes.
+
+    If you want to use a local certbot installation, you can omit the configurations for port 80 and change the SSL certificate parameters accordingly.
+    **Make sure you run a post-hook script** when you decide to use external ACME clients. You will find an example at the bottom of this page.
+
+
 2\. Configure your local webserver as reverse proxy:
 
 ### Apache 2.4
+Required modules:
+```
+a2enmod rewrite proxy proxy_http headers ssl
+```
+
 ``` apache
+<VirtualHost *:80>
+  ServerName CHANGE_TO_MAILCOW_HOSTNAME
+  ServerAlias autodiscover.*
+  ServerAlias autoconfig.*
+  RewriteEngine on
+  RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
+</VirtualHost>
 <VirtualHost *:443>
-    ServerName mail.example.org
+  ServerName CHANGE_TO_MAILCOW_HOSTNAME
-    ServerAlias autodiscover.example.org
+  ServerAlias autodiscover.*
-    ServerAlias autoconfig.example.org
+  ServerAlias autoconfig.*
 
-    [...]
+  # You should proxy to a plain HTTP session to offload SSL processing
-    # You should proxy to a plain HTTP session to offload SSL processing
+  ProxyPass / http://127.0.0.1:8080/
-    ProxyPass / http://127.0.0.1:8080/
+  ProxyPassReverse / http://127.0.0.1:8080/
-    ProxyPassReverse / http://127.0.0.1:8080/
 
-    ProxyPreserveHost On
+  ProxyPreserveHost On
-    ProxyAddHeaders On
+  ProxyAddHeaders On
 
-    # This header does not need to be set when using http
+  # This header does not need to be set when using http
-    RequestHeader set X-Forwarded-Proto "https"
+  RequestHeader set X-Forwarded-Proto "https"
 
-    your-ssl-configuration-here
+  # Change the pathes if necessary!
-    [...]
+  SSLCertificateFile /opt/mailcow-dockerized/data/assets/ssl/cert.pem
+  SSLCertificateKeyFile /opt/mailcow-dockerized/data/assets/ssl/key.pem
 
-    # If you plan to proxy to a HTTPS host:
+  # If you plan to proxy to a HTTPS host:
-    #SSLProxyEngine On
+  #SSLProxyEngine On
 
-    # If you plan to proxy to an untrusted HTTPS host:
+  # If you plan to proxy to an untrusted HTTPS host:
-    #SSLProxyVerify none
+  #SSLProxyVerify none
-    #SSLProxyCheckPeerCN off
+  #SSLProxyCheckPeerCN off
-    #SSLProxyCheckPeerName off
+  #SSLProxyCheckPeerName off
-    #SSLProxyCheckPeerExpire off
+  #SSLProxyCheckPeerExpire off
 </VirtualHost>
 ```
 
 ### Nginx
 ```
 server {
-    listen 443;
+  listen 80 default_server;
-    server_name mail.example.org autodiscover.example.org autoconfig.example.org;
+  listen [::]:80 default_server;
+  server_name CHANGE_TO_MAILCOW_HOSTNAME autodiscover.* autoconfig.*;
+  return 301 https://$host$request_uri;
+}
+server {
+  listen 443;
+  server_name CHANGE_TO_MAILCOW_HOSTNAME autodiscover.* autoconfig.*;
 
-    [...]
+  ssl on;
-    your-ssl-configuration-here
+  ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
+  ssl_ciphers         HIGH:!aNULL:!MD5;
 
-    location / {
+  # Change the pathes if necessary!
-        proxy_pass http://127.0.0.1:8080/;
+  ssl_certificate /opt/mailcow-dockerized/data/assets/ssl/cert.pem;
-        proxy_set_header Host $http_host;
+  ssl_certificate_key /opt/mailcow-dockerized/data/assets/ssl/key.pem;
-        proxy_set_header X-Real-IP $remote_addr;
+
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+  location / {
-        proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_pass http://127.0.0.1:8080/;
-        client_max_body_size 100m;
+    proxy_set_header Host $http_host;
-    }
+    proxy_set_header X-Real-IP $remote_addr;
-    [...]
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    client_max_body_size 0;
+  }
 }
 ```
 
 ### HAProxy
+
+**Important/Fixme**: This example only forwards HTTPS traffic and does not use mailcows built-in ACME client.
+
 ```
 frontend https-in
   bind :::443 v4v6 ssl crt mailcow.pem
@@ -79,3 +116,17 @@ backend mailcow
   http-request set-header X-Forwarded-Proto http if !{ ssl_fc }
   server mailcow 127.0.0.1:8080 check
 ```
+
+### Optional: Post-hook script for non-mailcow ACME clients
+
+Using a local certbot (or any other ACME client) requires to restart some containers, you can do this with a post-hook script.
+Make sure you change the pathes accordingly:
+```
+#!/bin/bash
+cp /etc/letsencrypt/live/my.domain.tld/fullchain.pem /opt/mailcow-dockerized/data/assets/ssl/cert.pem
+cp /etc/letsencrypt/live/my.domain.tld/privkey.pem /opt/mailcow-dockerized/data/assets/ssl/key.pem
+postfix_c=$(docker ps -qaf name=postfix-mailcow)
+dovecot_c=$(docker ps -qaf name=dovecot-mailcow)
+nginx_c=$(docker ps -qaf name=nginx-mailcow)
+docker restart ${postfix_c} ${dovecot_c} ${nginx_c}
+```