davina/core
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

[mod] readme

Browse source
This commit is contained in:
fenris 2025-09-22 20:29:56 +02:00
parent 213d1324bb
commit 3b272147a6
1 changed files with 22 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
readme.md
View file

@ -22,7 +22,7 @@
### Voraussetzungen ### 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 ### Anweisungen
@ -30,15 +30,11 @@
Zum lokalen Testen: Zum lokalen Testen:
- im build-Verzeichnis `php -S localhost:8000` ausführen - im build-Verzeichnis `php -S localhost:8000` ausführen
- CalDAV-Client einrichten mit Ziel-URL
- URL: `http://localhost:8000/calendars/-/rides`
- Nutzername: `<realm-name>`
- Passwort: ``
Für den Produktiv-Betrieb: 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 - Web-Server neustarten
@ -49,8 +45,8 @@ Der grobe Aufbau einer Konfigurations-Datei lässt sich in der [Beispiel-Konfigu
### Bezüge ### Bezüge
_Bezüge_/_Realms_ dienen die Daten-Quellen. Sie sind in der Konfiguration im Knoten `realms` zu erfassen. Jeder Bezug hat: _Bezüge_/_Realms_ dienen als Daten-Quellen. Sie sind in der Konfiguration im Knoten `realms` zu erfassen. Jeder Bezug hat:
- einen Namen (`name`), - einen eindeutigen Namen (`name`) — fließt in Authentifizierung und Ausgabe-URL ein
- eine Zugangs-Definition (`auth`) - eine Zugangs-Definition (`auth`)
- eine Quell-Definition (`source`) - eine Quell-Definition (`source`)
@ -79,8 +75,7 @@ _Authentifizierungen_ steuern wie auf einen Bezug zugegriffen wird.
#### Fest #### Fest
- es wird ein festes Passwort erwartet Es wird ein festes Passwort erwartet. Beispiel:
- Beispiel:
```json ```json
"auth": { "auth": {
@ -94,9 +89,7 @@ _Authentifizierungen_ steuern wie auf einen Bezug zugegriffen wird.
#### Durchleiten #### Durchleiten
- es wird kein bestimmtes Passwort erwartet Es wird kein bestimmtes Passwort erwartet; statt dessen wird d eingegebene Passwort an den Aufruf der Quelle weitergeleitet. Beispiel:
- das eingegebene Passwort wird an den Aufruf der Quelle weitergeleitet
- Beispiel:
```json ```json
"auth": { "auth": {
@ -107,33 +100,41 @@ _Authentifizierungen_ steuern wie auf einen Bezug zugegriffen wird.
### Quellen ### 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 #### 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 ```json
"source" :{ "source": {
"kind": "ics_feed", "kind": "ics_feed",
"data": { "data": {
"url": "https://events.example.org/concerts.ics", "url": "https://{{username}}:{{password}}@events.example.org/concerts.ics",
"conflate": true "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`. 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 ### Angaben für Clients
- Kalender-URL: `<url-base>/calendars/-/<realm-name>[-<calendar-name>]` - Kalender-URL: `<url-base>/calendars/-/<realm-name>[-<calendar-name>]` (`-<calendar-name>` nur setzen, wenn für die Quelle des Bezuges `"conflate": false` gesetzt ist)
- Nutzername: `<realm-name>[-<auth-username>]` - Nutzername: `<realm-name>[-<auth-username>]` (`-<auth-username>` nur relevant, wenn die Authentifizierung des Bezugs `"kind": "pass_trough"` gesetzt ist)
- Passwort: `<auth-password>` - Passwort: `<auth-password>`
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`