E-Mail-Autokonfiguration mit Docker, Caddy und Ansible – Migration einer bestehenden PHP-Lösung   Vor kurzem aktualisiert!


E-Mail-Autokonfiguration mit Docker
KI-generiertes Bild: E-Mail-Autokonfiguration mit Docker

In meinem älteren Beitrag „E-Mail-Autokonfiguration“ hatte ich beschrieben, wie sich die automatische Einrichtung von E-Mail-Konten für Thunderbird, Outlook und Apple-Geräte mit einer zentralen PHP-Anwendung realisieren lässt. Die Lösung hat sich im Alltag bewährt. Allerdings wurde sie ursprünglich direkt auf einem klassischen Apache-Webserver betrieben. PHP, virtuelle Hosts und die Let’s-Encrypt-Zertifikate mussten entsprechend verwaltet werden. Inzwischen betreibe ich zunehmend Dienste als Docker-Container und verwalte meine Serverkonfiguration vollständig mit Ansible. Deshalb stand die Frage im Raum: Wie lässt sich eine bereits funktionierende PHP-Autokonfiguration in einen Docker-Container migrieren, ohne ihre Funktionen zu verändern und ohne zusätzlichen Verwaltungsaufwand zu erzeugen?

In diesem Beitrag wird die Migration einschließlich HTTPS, DNS, automatisierter Tests, Monitoring und der anschließenden Stilllegung des alten Dienstes beschrieben.

1. Ausgangssituation

Die bisherige Lösung bestand im Wesentlichen aus:

  • einem Apache-Webserver mit PHP,
  • einer zentralen index.php,
  • Apache-VirtualHosts für autoconfig und autodiscover,
  • einem Let’s-Encrypt-Zertifikat mit mehreren Domainnamen,
  • und DNS-Einträgen, die alle Anfragen an denselben Server weiterleiteten.

Die Anwendung erzeugte abhängig vom aufgerufenen Hostnamen die passende Antwort für den jeweiligen E-Mail-Client.

Beispielsweise:

ClientEndpunkt
Thunderbirdhttps://autoconfig.example.com/mail/config-v1.1.xml
Outlookhttps://autodiscover.example.com/autodiscover/autodiscover.xml
Apple Mailhttps://autoconfig.example.com/apple

Diese Architektur war funktional, hatte aber einen Nachteil: Der Dienst war eng mit der Apache-Konfiguration und Zertifikatsverwaltung des bisherigen Servers verbunden.

2. Zielarchitektur

Die neue Lösung trennt die einzelnen Aufgaben deutlich voneinander:

  • Docker stellt die PHP-Anwendung bereit.
  • Apache im Container verarbeitet die Anfragen.
  • Caddy übernimmt HTTPS und den Reverse Proxy.
  • Ansible erzeugt und verwaltet sämtliche Konfigurationsdateien.
  • Uptime Kuma überwacht die öffentliche Erreichbarkeit.

Der Aufbau sieht vereinfacht so aus:

E-Mail-Client
     |
     | HTTPS
     v
autoconfig.example.com
autodiscover.example.com
     |
     v
   Caddy
   HTTPS / TLS
     |
     | Docker-Netzwerk: proxy
     v
 mail-autoconfig
 php:8.5-apache
     |
     v
   index.php
     |
     v
XML / Apple-Profil

Nur Caddy ist von außen erreichbar. Der Anwendungscontainer kommuniziert über das interne Docker-Netzwerk.

3. Die Ansible-Rolle

Für die neue Anwendung gibt es eine eigene Ansible-Rolle.

Die Verzeichnisstruktur ist überschaubar:

roles/mail_autoconfig/
├── defaults/
│   └── main.yml
├── files/
│   └── index.php
├── tasks/
│   └── main.yml
└── templates/
    ├── apache.conf.j2
    ├── docker-compose.yml.j2
    └── mail-settings.json.j2

Damit werden sowohl die Anwendung als auch die benötigten Konfigurationsdateien zentral verwaltet.

Konfiguration über Variablen

Die grundlegenden Einstellungen liegen in defaults/main.yml:

mail_autoconfig_dir: /root/docker/mail-autoconfig
mail_autoconfig_image: php:8.5-apache
mail_autoconfig_container_name: mail-autoconfig
mail_autoconfig_proxy_network_name: proxy

mail_autoconfig_imap:
  host: mail.example.com
  port: 143
  security: STARTTLS

mail_autoconfig_smtp:
  host: mail.example.com
  port: 587
  security: STARTTLS

mail_autoconfig_domains:
  example.com:
    display_name: "Beispiel GmbH"
    short_name: "Beispiel"

  example.net:
    display_name: "Zweite Beispieldomain"
    short_name: "Beispiel"

Die Domainliste ist dabei besonders wichtig. Die Anwendung muss nicht mehr selbst eine feste Liste von Domainnamen enthalten. Stattdessen werden die Einstellungen aus Ansible in eine JSON-Konfiguration übertragen, die PHP zur Laufzeit einliest. So können unterschiedliche Anzeigenamen je Domain definiert werden, während IMAP- und SMTP-Server zentral konfiguriert bleiben. Nicht konfigurierte Maildomains werden abgewiesen, statt automatisch beliebige Hostnamen zu akzeptieren.

4. Der Docker-Container

Als Grundlage verwende ich das offizielle Image:

php:8.5-apache

Ein vollständiges eigenes Docker-Image ist für diese kleine PHP-Anwendung nicht notwendig. Die Anwendung und ihre Konfigurationen werden als Bind-Mounts eingebunden. Eine vereinfachte Docker-Compose-Konfiguration sieht folgendermaßen aus:

services:
  mail-autoconfig:
    image: php:8.5-apache
    container_name: mail-autoconfig
    restart: unless-stopped

    volumes:
      - ./index.php:/var/www/html/index.php:ro
      - ./mail-settings.json:/var/www/html/mail-settings.json:ro
      - ./apache.conf:/etc/apache2/sites-available/000-default.conf:ro

    networks:
      - proxy

networks:
  proxy:
    external: true

Die hier gezeigte Compose-Datei ist ein vereinfachtes Beispiel. Die tatsächlich verwendeten Pfade und Mounts müssen zur jeweiligen Anwendung passen.

Entscheidend sind drei Punkte:

  1. Der Container benötigt keine eigene Datenbank.
  2. Die Konfigurationsdateien werden durch Ansible generiert.
  3. Der Container veröffentlicht keinen Port direkt auf dem Docker-Host.

Die Anwendung ist damit praktisch zustandslos.

5. HTTPS mit Caddy

Die bisherigen Apache-VirtualHosts und die manuelle Certbot-Verwaltung werden durch Caddy ersetzt. Für jede Domain werden zwei öffentliche Hostnamen verwendet:

autoconfig.example.com
autodiscover.example.com

autoconfig.example.net
autodiscover.example.net

Die Caddy-Konfiguration wird ebenfalls aus Ansible-Variablen generiert.

Ein Beispiel:

caddy_sites:
  - hostname: autoconfig.example.com
    upstream: mail-autoconfig:80
    access_log: true

  - hostname: autodiscover.example.com
    upstream: mail-autoconfig:80
    access_log: true

Caddy übernimmt anschließend die HTTPS-Terminierung und fordert die benötigten Zertifikate automatisch an. Der PHP-Container selbst arbeitet weiterhin über HTTP auf Port 80 – allerdings ausschließlich innerhalb des Docker-Netzwerks. Das reduziert die Komplexität gegenüber der bisherigen Installation erheblich.

6. DNS-Migration

Für die Umstellung mussten die bestehenden DNS-Einträge auf den neuen Server zeigen.

In meinem Fall verwende ich CNAME-Einträge:

HostnameTypZiel
autoconfig.example.comCNAMEautoconfig.example.net
autodiscover.example.comCNAMEautoconfig.example.net

Der zentrale Zielhostname verweist wiederum per A-Record auf die öffentliche IP-Adresse des neuen Servers.

Diese Konstruktion hat den Vorteil, dass bei einem späteren Serverwechsel nicht sämtliche Domain-Einträge einzeln angepasst werden müssen.

DNS-Einträge sollten möglichst vor der Aktivierung neuer HTTPS-Hostnamen angelegt und auf den autoritativen Nameservern überprüft werden.

Hilfreich sind beispielsweise:

dig +short NS example.com

dig @ns1.example.net \
  autodiscover.example.com CNAME

Der Nameservername ist hier nur ein Platzhalter und muss durch den tatsächlich zuständigen Nameserver ersetzt werden.

7. Deployment mit Ansible

Sobald die Rolle eingebunden und die Variablen definiert sind, lässt sich die Anwendung mit einem einzelnen Ansible-Aufruf bereitstellen:

ansible-playbook -i inventory.yml playbook.yml \
  --limit mailhost \
  --tags mail_autoconfig \
  --ask-vault-pass

Die Caddy-Konfiguration wird unabhängig davon aktualisiert:

ansible-playbook -i inventory.yml playbook.yml \
  --limit mailhost \
  --tags caddy \
  --ask-vault-pass

Damit ist die gesamte Bereitstellung reproduzierbar.

Ein späterer Serverwechsel erfordert keine manuelle Installation von PHP, keine Einrichtung einzelner Apache-VirtualHosts auf dem Hostsystem und keine gesonderte Certbot-Konfiguration für die Mail-Autokonfiguration.

8. Automatisierte Funktionstests

Ein wichtiger Bestandteil der Migration war die Ergänzung automatisierter Funktionstests. Dafür werden zwei Dateien verwendet:

tests/mail_autoconfig.yml
tests/mail_autoconfig_probe.py

Das Ansible-Test-Playbook liest die konfigurierten Hostnamen aus den vorhandenen Caddy-Variablen. Dadurch müssen die Domains nicht ein zweites Mal in einer Testliste gepflegt werden. Die Tests prüfen unter anderem:

  • HTTPS-Erreichbarkeit und Zertifikatsvalidierung,
  • Thunderbird-Autoconfig-XML,
  • Outlook-Autodiscover-Antworten,
  • Apple-Konfigurationsprofile auf gültige Plist-Syntax,
  • und den zusätzlichen .well-known-Endpunkt.

Ausgeführt werden sie beispielsweise mit:

ansible-playbook -i inventory.yml \
  tests/mail_autoconfig.yml \
  --limit mailhost \
  --ask-vault-pass

Beim abschließenden Test wurden 16 öffentliche Hostnamen für acht Maildomains erfolgreich überprüft.

Das Ergebnis:

16 configured hosts; 0 failure(s)

Besonders nützlich war, dass die Tests einen fehlenden DNS-Eintrag und anschließend den vorübergehenden TLS-Fehler zuverlässig erkannt haben. Ein Funktionstest ist deshalb mehr als eine einmalige Migrationskontrolle: Er lässt sich auch nach Docker-, PHP- oder Caddy-Updates erneut ausführen. Die tatsächliche Einrichtung wurde zusätzlich mit Thunderbird getestet. Die Outlook- und Apple-Ausgaben wurden strukturell geprüft; vollständige Praxistests mit diesen Clients stehen noch aus.

9. Monitoring mit Uptime Kuma

Nach der erfolgreichen Migration habe ich zusätzlich einen Monitor in Uptime Kuma eingerichtet. Dieser überprüft regelmäßig den Thunderbird-Autoconfig-Endpunkt:

https://autoconfig.example.com/mail/config-v1.1.xml

Dabei wird nicht nur ein HTTP-Status von 200 erwartet, sondern auch ein charakteristischer XML-Inhalt:

<clientConfig

Das ist sinnvoll, weil eine Anwendung unter Umständen noch HTTP 200 zurückliefert, obwohl sie nicht mehr die erwartete Konfiguration erzeugt. Uptime Kuma überwacht den laufenden Dienst kontinuierlich. Die Ansible-Funktionstests dienen dagegen der umfassenderen Überprüfung aller konfigurierten Endpunkte. Beide Verfahren ergänzen sich.

10. Den bisherigen Server stilllegen

Nachdem DNS, HTTPS, die Anwendung und die Funktionstests erfolgreich waren, konnte die bisherige Autokonfiguration auf dem alten Apache-Server deaktiviert werden. Dabei war wichtig, nicht einfach den gesamten Apache-Dienst abzuschalten. Auf dem alten Server liefen weiterhin andere Anwendungen. Deshalb wurden ausschließlich die bisherigen Autoconfig-VirtualHosts deaktiviert. Zusätzlich zeigte die Überprüfung, dass der HTTP-Default-VirtualHost noch auf das alte Autoconfig-Verzeichnis verwies. Dieser wurde auf ein neutrales DocumentRoot umgestellt.

Anschließend:

apache2ctl configtest
systemctl reload apache2

Nach einer erneuten Prüfung der aktiven VirtualHosts konnte auch das nicht mehr benötigte Let’s-Encrypt-Zertifikat entfernt werden. Dafür wurde der reguläre Certbot-Befehl verwendet:

certbot delete --cert-name autoconfig.example.com

Die Zertifikate der weiterhin betriebenen Dienste blieben unangetastet. Ein abschließender Test mit

certbot renew --dry-run

bestätigte, dass deren Zertifikatserneuerung weiterhin funktionierte. Die bisherige Anwendung wurde zunächst als Rückfallmöglichkeit aufbewahrt.

11. Automatisch generierte Dokumentation

Die technische Migration war soweit abgeschlossen. Zusätzlich sollte vermieden werden, dass die Domainliste künftig an mehreren Stellen gepflegt werden muss. Die Serverdokumentation wird bereits mit Ansible aus einem Jinja2-Template erzeugt. Diese Dokumentation wurde jetzt um die Mail-Autokonfiguration erweitert.

Der neue Abschnitt enthält automatisiert:

  • Docker-Image, Containername und Netzwerk,
  • IMAP- und SMTP-Konfiguration,
  • alle unterstützten Maildomains mit Anzeigenamen,
  • die zugehörigen öffentlichen Caddy-Hostnamen,
  • Test- und Monitoringinformationen,
  • sowie Hinweise zur Wiederherstellung.

Die Dokumentation erkennt außerdem, ob für eine konfigurierte Maildomain beide öffentlichen Hostnamen in Caddy hinterlegt sind. Das ist besonders praktisch: Eine fehlende Caddy-Route wird dadurch bereits in der generierten Dokumentation sichtbar.

12. Benötigt der Container ein eigenes Backup?

Für diese Anwendung lautet die Antwort: Nein, nicht unbedingt. Die Mail-Autokonfiguration speichert keine Benutzerdaten und besitzt keine eigene Datenbank. Alle benötigten Dateien liegen im Ansible-Repository oder werden beim Deployment daraus erzeugt. Für eine Wiederherstellung benötigt man deshalb hauptsächlich:

  • ein gesichertes Ansible-Repository,
  • die benötigten Zugangsdaten und Vault-Dateien,
  • eine funktionsfähige Docker-Infrastruktur,
  • sowie die passende Caddy- und DNS-Konfiguration.

Ein separates Backup des Containers bringt hier nur wenig zusätzlichen Nutzen. Voraussetzung ist natürlich, dass das Ansible-Repository selbst zuverlässig gesichert wird.

Fazit..

Die eigentliche PHP-Anwendung hat sich bei der Migration kaum verändert. Die entscheidende Verbesserung liegt in der Art, wie sie betrieben wird. Aus einer direkt auf einem Apache-Server installierten Anwendung wurde ein kleiner, zustandsloser Docker-Dienst, dessen gesamte Konfiguration über Ansible verwaltet wird. Caddy übernimmt die TLS-Zertifikate, Uptime Kuma das kontinuierliche Monitoring und ein eigenes Ansible-Test-Playbook die Überprüfung der öffentlichen Endpunkte. Dadurch ist die Lösung inzwischen deutlich einfacher zu warten und bei Bedarf auf einem neuen Server erneut bereitzustellen.

Wer zunächst die grundlegende Funktionsweise der Mail-Autokonfiguration kennenlernen möchte, findet die ursprüngliche Umsetzung in meinem ersten Beitrag: E-Mail-Autokonfiguration mit Apache und PHP