diff --git a/readme.md b/readme.md index 30db4d7..b81747c 100644 --- a/readme.md +++ b/readme.md @@ -22,7 +22,7 @@ ### Voraussetzungen -- Web-Server mit PHP-FPM-Unterstützung (für Test-Zwecke reicht der PHP-Development-Server) +- Web-Server mit PHP-CGI-Unterstützung (für Test-Zwecke reicht der PHP-Development-Server) ### Anweisungen @@ -30,15 +30,11 @@ Zum lokalen Testen: - im build-Verzeichnis `php -S localhost:8000` ausführen -- CalDAV-Client einrichten mit Ziel-URL - - URL: `http://localhost:8000/calendars/-/rides` - - Nutzername: `` - - Passwort: `` Für den Produktiv-Betrieb: -- Host-Konfiguration für den Web-Server anlegen +- Host-Konfiguration für den Web-Server anlegen (Templates: [nginx](https://forgejo.ramsch.sx/misc/davina-infrastructure/src/branch/main/roles/davina_backend-and-nginx/templates/conf.j2)) - Web-Server neustarten @@ -49,8 +45,8 @@ Der grobe Aufbau einer Konfigurations-Datei lässt sich in der [Beispiel-Konfigu ### Bezüge -_Bezüge_/_Realms_ dienen die Daten-Quellen. Sie sind in der Konfiguration im Knoten `realms` zu erfassen. Jeder Bezug hat: -- einen Namen (`name`), +_Bezüge_/_Realms_ dienen als Daten-Quellen. Sie sind in der Konfiguration im Knoten `realms` zu erfassen. Jeder Bezug hat: +- einen eindeutigen Namen (`name`) — fließt in Authentifizierung und Ausgabe-URL ein - eine Zugangs-Definition (`auth`) - eine Quell-Definition (`source`) @@ -79,8 +75,7 @@ _Authentifizierungen_ steuern wie auf einen Bezug zugegriffen wird. #### Fest -- es wird ein festes Passwort erwartet -- Beispiel: +Es wird ein festes Passwort erwartet. Beispiel: ```json "auth": { @@ -94,9 +89,7 @@ _Authentifizierungen_ steuern wie auf einen Bezug zugegriffen wird. #### Durchleiten -- es wird kein bestimmtes Passwort erwartet -- das eingegebene Passwort wird an den Aufruf der Quelle weitergeleitet -- Beispiel: +Es wird kein bestimmtes Passwort erwartet; statt dessen wird d eingegebene Passwort an den Aufruf der Quelle weitergeleitet. Beispiel: ```json "auth": { @@ -107,33 +100,41 @@ _Authentifizierungen_ steuern wie auf einen Bezug zugegriffen wird. ### Quellen -_Quellen_ sind die Stellen, die aufgerufen werden um die rohen Kalender-Daten zu erhalten. +_Quellen_ beschreiben wie die rohen Kalender-Daten für einen Bezug gelesen werden. #### ICS-Feed -Kalender-Daten, welche im [iCalendar](https://de.wikipedia.org/wiki/ICalendar)-Format `ics` vorliegen, können wie folgt eingebunden werden: +Kalender-Daten, welche im [iCalendar](https://de.wikipedia.org/wiki/ICalendar)-Format `ics` im Netz abrufbar sind, können wie folgt eingebunden werden: ```json -"source" :{ +"source": { "kind": "ics_feed", "data": { - "url": "https://events.example.org/concerts.ics", - "conflate": true + "url": "https://{{username}}:{{password}}@events.example.org/concerts.ics", + "conflate": true, + "from_fucked_up_wordpress": false } } ``` -`url` ist hierbei schlicht die URL zur `ics`-Datei. Diese kann man den Platzhaltern `{{username}}` und `{{password}}` versehen sein. Im Fall einer Authentifizierung mittels Durchleiten, werden diese Platzhalter durch die konkret vorliegenden Werte ersetzt. +`url` ist hierbei schlicht die URL zur `ics`-Datei. Diese kann mit den Platzhaltern `{{username}}` und `{{password}}` versehen sein. Im Fall einer Authentifizierung mittels Durchleiten, werden diese Platzhalter durch die konkret vorliegenden Werte ersetzt. Der Schalter `conflate` steuert, ob die erhaltenen Termine in einen Kalender zusammengefasst werden sollen, statt sie gemäß ihrer `VEVENT`-Feld-Werte `CATEGORIES` aufzutrennen. Das hat Auswirkungen auf die URL, die man im CalDAV-Client einstellen muss. Kommen in einer `ics`-Datei bspw. die `CATEGORIES`-Werte `day` und `night` vor und der Bezug hat den Name `music`, dann würden bei `"conflate": false` die Ziel-URL-Pfade `/calendars/-/music-day` und `/calendars/-/music-night` anliegen; bei `"conflate": true` nur `/calendars/-/music`. +Den Schalter `from_fucked_up_wordpress` sollte man setzen, wenn die `ics`-Datei von einer Wordpress-Instanz mit üblichem Kalender-Plugin ist. + ### Angaben für Clients -- Kalender-URL: `/calendars/-/[-]` -- Nutzername: `[-]` +- Kalender-URL: `/calendars/-/[-]` (`-` nur setzen, wenn für die Quelle des Bezuges `"conflate": false` gesetzt ist) +- Nutzername: `[-]` (`-` nur relevant, wenn die Authentifizierung des Bezugs `"kind": "pass_trough"` gesetzt ist) - Passwort: `` +Spielt man die [Beispiel-Konfiguration](misc/conf-example.dvn.json) lokal über Port `8000` aus, würden diese Werte lauten: + +- Kalender-URL: `http://localhost:8000/calendars/-/holidays` +- Nutzername: `holidays` +- Passwort: `secret`