Schnellstart

Voraussetzungen

Eine laufende Mailcow-Instanz mit Docker Compose
Ein API-Key mit Lese-/Schreibzugriff (Admin-Panel → Konfiguration → Zugang → Administratordetails bearbeiten → API)

Installation

Den folgenden Abschnitt in die docker-compose.override.yml der Mailcow-Installation einfügen (z. B. /opt/mailcow-dockerized/docker-compose.override.yml):

Warum docker-compose.override.yml? Das Projekt mailcow-dockerized verwaltet seine eigene docker-compose.yml und überschreibt diese bei Updates. Eigene Ergänzungen in der Hauptdatei würden dadurch verloren gehen. Docker Compose erkennt eine docker-compose.override.yml im selben Verzeichnis automatisch und mergt deren Inhalte mit der Hauptkonfiguration. Der Birthday Daemon wird so sauber in den Mailcow-Stack integriert, ohne die originale Konfiguration zu verändern.

services:
    birthdaydaemon:
        image: git.techniverse.net/scriptos/mailcow-birthday-daemon:latest
        restart: always
        depends_on:
            - nginx-mailcow
        networks:
            - mailcow-network
        environment:
            - MAILCOW_BASE=https://mail.example.com
            - MAILCOW_APIKEY=DEIN-APIKEY-HIER
            - CALENDAR_NAME=Birthdays
            # - MAILCOW_RESOLVE_HOST=nginx-mailcow
            # - NOTIFICATION_ENABLED=true
            # - NOTIFICATION_TIME=08:00
        volumes:
            - birthdaydaemon:/data

volumes:
    birthdaydaemon:

Wichtig: mail.example.com muss durch den tatsächlichen FQDN der eigenen Mailcow-Instanz ersetzt werden.

Hinweis zu MAILCOW_RESOLVE_HOST: Innerhalb eines Docker-Netzes kann der Container die öffentliche Domain (z. B. mail.example.com) oft nicht über die externe IP erreichen – ein typisches Hairpin-NAT-Problem. Die Variable MAILCOW_RESOLVE_HOST=nginx-mailcow sorgt dafür, dass TCP-Verbindungen direkt an den Mailcow-Nginx-Container im selben Docker-Netz aufgebaut werden, anstatt den Umweg über die öffentliche IP zu nehmen. TLS-SNI und die Zertifikatsprüfung verwenden dabei weiterhin den Hostnamen aus MAILCOW_BASE, sodass die Verbindung korrekt verschlüsselt bleibt.

Tipp: Statt :latest kann auch eine feste Version wie :0.3.0 verwendet werden. Alle verfügbaren Tags sind in der Container Registry einsehbar.

Container starten

Nach der Konfiguration der Variablen kann der Container initial gestartet werden.

cd /opt/mailcow-dockerized
docker compose pull birthdaydaemon && docker compose up -d --no-deps birthdaydaemon

Hinweis: Nach dem Start wartet der Daemon zunächst 15 Sekunden, bevor die erste Synchronisation beginnt. Diese Verzögerung stellt sicher, dass abhängige Dienste (z. B. Nginx, SOGo) vollständig bereit sind.

Umgebungsvariablen

Variable	Pflicht	Standardwert	Beschreibung
`MAILCOW_BASE`	Ja	–	Basis-URL der Mailcow-Instanz (z. B. `https://mailcow.example.com`)
`MAILCOW_APIKEY`	Ja	–	API-Key mit Lese-/Schreibzugriff aus dem Mailcow-Admin-Panel
`MAILCOW_RESOLVE_HOST`	Nein	–	Interner Hostname für TCP-Verbindungen (z. B. `nginx-mailcow`). Löst Hairpin-NAT-Probleme in Docker-Netzen. TLS nutzt weiterhin den Hostnamen aus `MAILCOW_BASE`.
`CALENDAR_NAME`	Nein	`Birthdays`	Name des Geburtstagskalenders, der in jeder Mailbox erstellt wird
`NOTIFICATION_ENABLED`	Nein	`false`	Aktiviert Kalender-Benachrichtigungen (VALARM) für Geburtstags-Events (`true`/`false`)
`NOTIFICATION_TIME`	Nein	`08:00`	Uhrzeit der Benachrichtigung im Format `HH:MM` (nur wirksam wenn `NOTIFICATION_ENABLED=true`)
`STATEFILE`	Nein	`state.json` (im Container: `/data/state.json`)	Pfad zur Zustandsdatei, in der App-Passwörter und der aktuelle Kalendername gespeichert werden

API-Key erstellen

Den API-Key findet man im Admin-Panel unter Konfiguration → Zugang → Administratordetails bearbeiten → API → Lese-/Schreibzugriff.

Warnung: Da die Mailcow-API derzeit nicht vollständig ist und sich eher im Early-Access-Stadium befindet, wird dringend davon abgeraten, die Option „IP-Prüfung für API überspringen" zu aktivieren. (siehe Bild)

Prüfen, ob alles läuft

cd /opt/mailcow-dockerized
docker compose logs -f birthdaydaemon

Nach dem Start synchronisiert der Daemon automatisch alle 15 Minuten die Geburtstagskalender für jede Mailbox.

Hinweis für bestehende Installationen: Falls der Daemon die Mailcow-API wegen Hairpin-NAT nicht erreichen kann, muss lediglich MAILCOW_RESOLVE_HOST=nginx-mailcow als Umgebungsvariable ergänzt werden. Details siehe Installationsabschnitt.

Bei Problemen: Siehe Troubleshooting.

Wie funktioniert der Daemon im Detail? Siehe Funktionsweise.

4.9 KiB Raw Permalink Blame History Unescape Escape