From 404ac5a438feaec2013367e00f5af40129bf0b71 Mon Sep 17 00:00:00 2001
From: youtous <contact@youtous.me>
Date: Thu, 23 Apr 2020 15:49:52 +0200
Subject: [PATCH] add ssl doc: traefik

---
 docs/content/config/security/ssl.md | 64 +++++++++++++++++++++++++++--
 1 file changed, 60 insertions(+), 4 deletions(-)

diff --git a/docs/content/config/security/ssl.md b/docs/content/config/security/ssl.md
index c7c899c1..a222fced 100644
--- a/docs/content/config/security/ssl.md
+++ b/docs/content/config/security/ssl.md
@@ -1,10 +1,13 @@
 There are multiple options to enable SSL:
 
-* using [letsencrypt](https://letsencrypt.org/) (recommended)
-* using self-signed certificates with the provided tool
-* using your own certificates
+* using [letsencrypt](#lets-encrypt-recommended) (recommended)
+* using [traefik](#traefik)
+* using [self-signed certificates](#self-signed-certificates-testing-only) with the provided tool
+* using [your own certificates](#custom-certificate-files)
 
-After installation, you can test your setup with [checktls.com](https://www.checktls.com/TestReceiver).
+After installation, you can test your setup with:
+- [checktls.com](https://www.checktls.com/TestReceiver)
+- [testssl.sh](https://github.com/drwetter/testssl.sh)
 
 ### Let's encrypt (recommended)
 
@@ -211,6 +214,59 @@ environment:
 ```
 DSM-generated letsencrypt certificates get auto-renewed every three months.
 
+### Traefik
+
+[Traefik](https://github.com/containous/traefik) is an open-source Edge Router which handles ACME protocol using [lego](https://github.com/go-acme/lego).
+Traefik can request certificates for domains trougth the ACME protocol, the router will take care of renewals, challenge negotiations etc.
+
+If you are using traefik you might want to push your certificates in the *mailserver* container. 
+[youtous/mailserver-traefik](https://github.com/youtous/docker-mailserver-traefik) is a certificate renewal service for [tomav/dockermailserver](https://github.com/tomav/docker-mailserver/) relying on the [traefik acme storage](https://docs.traefik.io/https/acme/).
+
+#### Getting started
+
+Depending of your traefik configuration, certificates could be stored using a *file* or a *KV Store (consul, etcd...)*
+
+_docker-compose example:_
+```
+services:
+  cert-renewer-traefik:
+    image: youtous/mailserver-traefik:latest
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./acme.json:/tmp/traefik/acme.json:ro # link traefik acme.json file (read-only)
+    environment:
+      - TRAEFIK_VERSION=2
+      - CERTS_SOURCE=file
+      - DOMAINS=mail.localhost.com
+
+  mailserver:
+    image: tvial/docker-mailserver:latest
+    hostname: mail
+    domainname: localhost.com
+    labels:
+      - "mailserver-traefik.renew.domain=mail.localhost.com" # tag the service 
+
+      # traefik service declaration (you can use static configuration too)
+      - "traefik.enable=true"
+      - "traefik.port=443" # dummy port, required generating certs with traefik
+
+      - "traefik.http.routers.mail.rule=Host(`mail.localhost.com`)" 
+      - "traefik.http.routers.mail.entrypoints=websecure"
+      - "traefik.http.routers.mail.middlewares=redirect-webmail@docker" # /!\ the router must redirect every requests.
+      - "traefik.http.middlewares.redirect-webmail.redirectregex.regex=.*"
+      - "traefik.http.middlewares.redirect-webmail.redirectregex.replacement=https://webmail.localhost.com/"
+    
+   environment:
+      - SSL_TYPE=manual # enable SSL on the *mailserver* and store certificates in pre-defined paths
+      - SSL_CERT_PATH=/var/mail-state/manual-ssl/cert # don't change theses paths!
+      - SSL_KEY_PATH=/var/mail-state/manual-ssl/key
+```
+
+Certificates will be renewed by *traefik* then pushed in the *mailserver* by the *cert-renewer* service, finally, dovecot and postfix will be restarted.
+<br>
+Documentation: https://github.com/youtous/docker-mailserver-traefik.
+
+
 ### Self-signed certificates (testing only)
 
 You can easily generate a self-signed SSL certificate by using the following command: