diff --git a/docs/firststeps-rp.md b/docs/firststeps-rp.md
index a1b0a0855..94316d0dc 100644
--- a/docs/firststeps-rp.md
+++ b/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
+
+ ServerName CHANGE_TO_MAILCOW_HOSTNAME
+ ServerAlias autodiscover.*
+ ServerAlias autoconfig.*
+ RewriteEngine on
+ RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
+
- ServerName mail.example.org
- ServerAlias autodiscover.example.org
- ServerAlias autoconfig.example.org
+ ServerName CHANGE_TO_MAILCOW_HOSTNAME
+ ServerAlias autodiscover.*
+ ServerAlias autoconfig.*
- [...]
- # You should proxy to a plain HTTP session to offload SSL processing
- ProxyPass / http://127.0.0.1:8080/
- ProxyPassReverse / http://127.0.0.1:8080/
+ # You should proxy to a plain HTTP session to offload SSL processing
+ ProxyPass / http://127.0.0.1:8080/
+ ProxyPassReverse / http://127.0.0.1:8080/
- ProxyPreserveHost On
- ProxyAddHeaders On
+ ProxyPreserveHost On
+ ProxyAddHeaders On
- # This header does not need to be set when using http
- RequestHeader set X-Forwarded-Proto "https"
+ # This header does not need to be set when using http
+ 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:
- #SSLProxyEngine On
-
- # If you plan to proxy to an untrusted HTTPS host:
- #SSLProxyVerify none
- #SSLProxyCheckPeerCN off
- #SSLProxyCheckPeerName off
- #SSLProxyCheckPeerExpire off
+ # If you plan to proxy to a HTTPS host:
+ #SSLProxyEngine On
+
+ # If you plan to proxy to an untrusted HTTPS host:
+ #SSLProxyVerify none
+ #SSLProxyCheckPeerCN off
+ #SSLProxyCheckPeerName off
+ #SSLProxyCheckPeerExpire off
```
### Nginx
```
server {
- listen 443;
- server_name mail.example.org autodiscover.example.org autoconfig.example.org;
+ listen 80 default_server;
+ 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.*;
- [...]
- your-ssl-configuration-here
+ ssl on;
+ ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
+ ssl_ciphers HIGH:!aNULL:!MD5;
- location / {
- proxy_pass http://127.0.0.1:8080/;
- 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 100m;
- }
- [...]
+ # Change the pathes if necessary!
+ ssl_certificate /opt/mailcow-dockerized/data/assets/ssl/cert.pem;
+ ssl_certificate_key /opt/mailcow-dockerized/data/assets/ssl/key.pem;
+
+ location / {
+ proxy_pass http://127.0.0.1:8080/;
+ 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}
+```
\ No newline at end of file