Edited Docs
This commit is contained in:
49
README.md
49
README.md
@@ -2,13 +2,16 @@
|
|||||||
|
|
||||||
> **Fork-Hinweis:** Dieses Projekt ist ein Fork von [Marco98/mailcow-birthday-daemon](https://github.com/Marco98/mailcow-birthday-daemon) und wird hier eigenständig weiterentwickelt.
|
> **Fork-Hinweis:** Dieses Projekt ist ein Fork von [Marco98/mailcow-birthday-daemon](https://github.com/Marco98/mailcow-birthday-daemon) und wird hier eigenständig weiterentwickelt.
|
||||||
|
|
||||||
Ein einfacher Daemon, der automatisch einen Geburtstagskalender für jede Mailcow-Mailbox erzeugt und synchronisiert.
|
Ein einfacher Daemon, der automatisch einen Geburtstagskalender für jede Mailcow-Mailbox erzeugt und synchronisiert. Es ist kein Benutzereingriff erforderlich – alles läuft vollautomatisch.
|
||||||
|
|
||||||
Es ist kein Benutzereingriff erforderlich. Alles wird vollautomatisch erledigt.
|
## Kurzübersicht
|
||||||
|
|
||||||
## Installation
|
- Liest Geburtstage aus allen CardDAV-Adressbüchern jeder Mailbox
|
||||||
|
- Erstellt und synchronisiert automatisch einen Geburtstagskalender pro Benutzer
|
||||||
|
- Synchronisation alle **15 Minuten**
|
||||||
|
- Läuft als Docker-Container direkt im Mailcow-Stack
|
||||||
|
|
||||||
Den folgenden Abschnitt in die `docker-compose.override.yml` einfügen:
|
## Schnellstart
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
services:
|
services:
|
||||||
@@ -22,7 +25,6 @@ services:
|
|||||||
environment:
|
environment:
|
||||||
- MAILCOW_BASE=https://mail.example.com
|
- MAILCOW_BASE=https://mail.example.com
|
||||||
- MAILCOW_APIKEY=DEIN-APIKEY-HIER
|
- MAILCOW_APIKEY=DEIN-APIKEY-HIER
|
||||||
- MAILCOW_RESOLVE_HOST=nginx-mailcow
|
|
||||||
volumes:
|
volumes:
|
||||||
- birthdaydaemon:/data
|
- birthdaydaemon:/data
|
||||||
|
|
||||||
@@ -30,35 +32,16 @@ volumes:
|
|||||||
birthdaydaemon:
|
birthdaydaemon:
|
||||||
```
|
```
|
||||||
|
|
||||||
> **Wichtig:** `mail.example.com` muss durch den tatsächlichen FQDN der eigenen Mailcow-Instanz ersetzt werden. `MAILCOW_RESOLVE_HOST=nginx-mailcow` sorgt dafür, dass der Daemon den Mailcow-Nginx innerhalb des Docker-Netzes direkt erreicht, anstatt über die öffentliche IP zu gehen (Hairpin-NAT-Problem). TLS-SNI und Zertifikatsprüfung verwenden weiterhin den Hostnamen aus `MAILCOW_BASE`.
|
> Alle verfügbaren Image-Tags sind in der [Container Registry](https://git.techniverse.net/scriptos/-/packages/container/mailcow-birthday-daemon) einsehbar.
|
||||||
|
|
||||||
> **Tipp:** Statt `:latest` kann auch eine feste Version wie `:1.0.0` verwendet werden.
|
## Dokumentation
|
||||||
|
|
||||||
Den API-Key findet man im Admin-Panel unter Konfiguration > Zugang > Administratordetails bearbeiten > API > Lese-/Schreibzugriff.
|
Die vollständige Dokumentation befindet sich im Ordner [`docs/`](docs/README.md).
|
||||||
|
|
||||||
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.
|
<p align="center">
|
||||||
|
<img src="https://assets.techniverse.net/f1/git/graphics/gray0-catonline.svg" alt="">
|
||||||
|
</p>
|
||||||
|
|
||||||
## Konfiguration (Umgebungsvariablen)
|
<p align="center">
|
||||||
|
<img src="https://assets.techniverse.net/f1/logos/small/license.png" alt="License" width="15" height="15"> <a href="./LICENSE">License</a> | <img src="https://assets.techniverse.net/f1/logos/small/matrix2.svg" alt="Matrix" width="15" height="15"> <a href="https://matrix.to/#/#community:techniverse.net">Matrix</a> | <img src="https://assets.techniverse.net/f1/logos/small/mastodon2.svg" alt="Mastodon" width="15" height="15"> <a href="https://social.techniverse.net/@donnerwolke">Mastodon</a>
|
||||||
| Variable | Pflicht | Standardwert | Beschreibung |
|
</p>
|
||||||
|---|---|---|---|
|
|
||||||
| `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. Bei Änderung wird der alte Daemon-Kalender automatisch entfernt und ein neuer erstellt (siehe unten). |
|
|
||||||
| `STATEFILE` | Nein | `state.json` (im Container: `/data/state.json`) | Pfad zur Zustandsdatei, in der App-Passwörter und der aktuelle Kalendername gespeichert werden |
|
|
||||||
|
|
||||||
> **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.
|
|
||||||
|
|
||||||
## Funktionsweise
|
|
||||||
|
|
||||||
- Über die Mailcow-API wird für jeden aktiven Benutzer ein App-Passwort mit Zugriff auf CardDAV und CalDAV erzeugt.
|
|
||||||
- Da jedes App-Passwort in Mailcow eine global hochzählende Nummer erhält, werden die Passwörter auf der Festplatte gespeichert, um das unnötige Ansteigen dieser Nummer zu vermeiden.
|
|
||||||
- Alle Kontakte aus sämtlichen Adressbüchern werden abgerufen und die Geburtstagsinformationen je Benutzer extrahiert.
|
|
||||||
- Die daraus resultierenden Kalendereinträge werden im Voraus berechnet.
|
|
||||||
- Aktuell fest eingestellt: 1 Jahr in der Vergangenheit, 10 Jahre in der Zukunft.
|
|
||||||
- Selbstverständlich pro Mailbox isoliert – ein Benutzer sieht nur die Geburtstage seiner eigenen Kontakte.
|
|
||||||
- Die berechneten Ereignisse werden in einen Kalender synchronisiert, dessen Name über `CALENDAR_NAME` konfigurierbar ist (Standard: „Birthdays"). Der Anzeigename kann vom Benutzer in SOGo zusätzlich umbenannt werden.
|
|
||||||
- Bei Änderung von `CALENDAR_NAME` wird der alte Kalender beim nächsten Start automatisch entfernt und ein neuer mit dem neuen Namen erstellt. Der alte Kalender wird dabei nur gelöscht, wenn er ausschließlich vom Daemon erstellte Einträge enthält – manuell angelegte Kalender mit gleichem Namen bleiben unangetastet.
|
|
||||||
- **Wichtig:** Damit die Umbenennung korrekt erkannt wird, muss der Daemon **mindestens einmal** mit dem neuen Code und dem **alten** Kalendernamen gelaufen sein, damit der Name im State-File gespeichert wird. Erst danach `CALENDAR_NAME` ändern und erneut starten. Wird der Name geändert, bevor der State aktualisiert wurde, kann der alte Kalender nicht automatisch entfernt werden und muss manuell gelöscht werden.
|
|
||||||
- Der Synchronisationszyklus läuft alle **15 Minuten** automatisch.
|
|
||||||
8
docs/README.md
Normal file
8
docs/README.md
Normal file
@@ -0,0 +1,8 @@
|
|||||||
|
# Dokumentation
|
||||||
|
|
||||||
|
Willkommen in der Dokumentation des **Mailcow Birthday Daemon** 🎂
|
||||||
|
|
||||||
|
## Inhaltsverzeichnis
|
||||||
|
|
||||||
|
- [Schnellstart](schnellstart.md) – Installation und erste Einrichtung
|
||||||
|
- [Update](update.md) – Bestehende Installation aktualisieren
|
||||||
82
docs/schnellstart.md
Normal file
82
docs/schnellstart.md
Normal file
@@ -0,0 +1,82 @@
|
|||||||
|
# Schnellstart
|
||||||
|
|
||||||
|
## Voraussetzungen
|
||||||
|
|
||||||
|
- Eine laufende [Mailcow](https://mailcow.email/)-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:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
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
|
||||||
|
- MAILCOW_RESOLVE_HOST=nginx-mailcow
|
||||||
|
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 `:1.0.0` verwendet werden. Alle verfügbaren Tags sind in der [Container Registry](https://git.techniverse.net/scriptos/-/packages/container/mailcow-birthday-daemon) einsehbar.
|
||||||
|
|
||||||
|
## Container starten
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /opt/mailcow-dockerized
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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 |
|
||||||
|
| `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.
|
||||||
|
|
||||||
|
## Prüfen, ob alles läuft
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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](#installation).
|
||||||
|
|
||||||
|
## Funktionsweise
|
||||||
|
|
||||||
|
- Über die Mailcow-API wird für jeden aktiven Benutzer ein App-Passwort mit Zugriff auf CardDAV und CalDAV erzeugt.
|
||||||
|
- Da jedes App-Passwort in Mailcow eine global hochzählende Nummer erhält, werden die Passwörter auf der Festplatte gespeichert, um das unnötige Ansteigen dieser Nummer zu vermeiden.
|
||||||
|
- Alle Kontakte aus sämtlichen Adressbüchern werden abgerufen und die Geburtstagsinformationen je Benutzer extrahiert.
|
||||||
|
- Die daraus resultierenden Kalendereinträge werden im Voraus berechnet.
|
||||||
|
- Aktuell fest eingestellt: 1 Jahr in der Vergangenheit, 10 Jahre in der Zukunft.
|
||||||
|
- Selbstverständlich pro Mailbox isoliert – ein Benutzer sieht nur die Geburtstage seiner eigenen Kontakte.
|
||||||
|
- Die berechneten Ereignisse werden in einen Kalender synchronisiert, dessen Name über `CALENDAR_NAME` konfigurierbar ist (Standard: „Birthdays"). Der Anzeigename kann vom Benutzer in SOGo zusätzlich umbenannt werden.
|
||||||
|
- Bei Änderung von `CALENDAR_NAME` wird der alte Kalender beim nächsten Start automatisch entfernt und ein neuer mit dem neuen Namen erstellt. Der alte Kalender wird dabei nur gelöscht, wenn er ausschließlich vom Daemon erstellte Einträge enthält – manuell angelegte Kalender mit gleichem Namen bleiben unangetastet.
|
||||||
|
- **Wichtig:** Damit die Umbenennung korrekt erkannt wird, muss der Daemon **mindestens einmal** mit dem neuen Code und dem **alten** Kalendernamen gelaufen sein, damit der Name im State-File gespeichert wird. Erst danach `CALENDAR_NAME` ändern und erneut starten. Wird der Name geändert, bevor der State aktualisiert wurde, kann der alte Kalender nicht automatisch entfernt werden und muss manuell gelöscht werden.
|
||||||
|
- Der Synchronisationszyklus läuft alle **15 Minuten** automatisch.
|
||||||
32
docs/update.md
Normal file
32
docs/update.md
Normal file
@@ -0,0 +1,32 @@
|
|||||||
|
# Update
|
||||||
|
|
||||||
|
## Image aktualisieren
|
||||||
|
|
||||||
|
Um den Mailcow Birthday Daemon auf die neueste Version zu aktualisieren, genügen folgende Schritte im Mailcow-Verzeichnis:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /opt/mailcow-dockerized
|
||||||
|
docker compose pull birthdaydaemon
|
||||||
|
docker compose up -d birthdaydaemon
|
||||||
|
```
|
||||||
|
|
||||||
|
## Auf eine bestimmte Version wechseln
|
||||||
|
|
||||||
|
1. Die gewünschte Version in der [Container Registry](https://git.techniverse.net/scriptos/-/packages/container/mailcow-birthday-daemon) auswählen.
|
||||||
|
2. Den Image-Tag in der `docker-compose.override.yml` anpassen:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
image: git.techniverse.net/scriptos/mailcow-birthday-daemon:1.0.0
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Container neu starten:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose up -d birthdaydaemon
|
||||||
|
```
|
||||||
|
|
||||||
|
## Hinweise
|
||||||
|
|
||||||
|
- Die Zustandsdatei (`/data/state.json`) im Volume `birthdaydaemon` bleibt bei Updates erhalten. Gespeicherte App-Passwörter werden weiterverwendet.
|
||||||
|
- Ein Neustart des Containers löst sofort einen Synchronisationszyklus aus.
|
||||||
|
- Falls sich der Standard-Kalendername (`CALENDAR_NAME`) mit einem Update ändert, siehe den Abschnitt zur Kalender-Umbenennung in der [Schnellstart-Dokumentation](schnellstart.md#funktionsweise).
|
||||||
Reference in New Issue
Block a user