139 lines
3.7 KiB
Markdown
139 lines
3.7 KiB
Markdown
# davina
|
|
|
|
- bereitet rohe Kalender-Daten aus verschiedenen Quellen mittels CalDAV auf und stellt diese als Server bereit
|
|
- basiert auf [sabre/dav](https://sabre.io/dav/)
|
|
|
|
|
|
## Erstellung
|
|
|
|
### Voraussetzungen
|
|
|
|
(keine)
|
|
|
|
|
|
### Anweisungen
|
|
|
|
- `tools/build` ausführen (Schalter `-h` anfügen für Erklärungen)
|
|
|
|
|
|
## Betrieb
|
|
|
|
### Voraussetzungen
|
|
|
|
- Web-Server mit PHP-CGI-Unterstützung (für Test-Zwecke reicht der PHP-Development-Server)
|
|
|
|
|
|
### Anweisungen
|
|
|
|
Zum lokalen Testen:
|
|
|
|
- im build-Verzeichnis `php -S localhost:8000` ausführen
|
|
|
|
|
|
Für den Produktiv-Betrieb:
|
|
|
|
- Host-Konfiguration für den Web-Server anlegen (Templates: [nginx](/davina/infrastructure/src/branch/main/roles/davina_core-and-nginx/templates/conf.j2))
|
|
- Web-Server neustarten
|
|
|
|
|
|
## Dokumentation
|
|
|
|
Der grobe Aufbau einer Konfigurations-Datei lässt sich in der [Beispiel-Konfiguration](misc/conf-example.dvn.json) sehen.
|
|
|
|
|
|
### Bezüge
|
|
|
|
_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`)
|
|
|
|
Beispiel:
|
|
|
|
```json
|
|
"realms": [
|
|
{
|
|
"name": "foo",
|
|
"auth": …
|
|
"source": …
|
|
},
|
|
{
|
|
"name": "bar",
|
|
"auth": …
|
|
"source": …
|
|
}
|
|
]
|
|
…
|
|
```
|
|
|
|
### Authentifizierungen
|
|
|
|
_Authentifizierungen_ steuern wie auf einen Bezug zugegriffen wird.
|
|
|
|
|
|
#### Fest
|
|
|
|
Es wird ein festes Passwort erwartet. Beispiel:
|
|
|
|
```json
|
|
"auth": {
|
|
"kind": "static",
|
|
"data": {
|
|
"password": "secret"
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
#### Durchleiten
|
|
|
|
Es wird kein bestimmtes Passwort erwartet; statt dessen wird das eingegebene Passwort an den Aufruf der Quelle weitergeleitet. Beispiel:
|
|
|
|
```json
|
|
"auth": {
|
|
"kind": "pass_through"
|
|
}
|
|
```
|
|
|
|
|
|
### Quellen
|
|
|
|
_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` im Netz abrufbar sind, können wie folgt eingebunden werden:
|
|
|
|
|
|
```json
|
|
"source": {
|
|
"kind": "ics_feed",
|
|
"data": {
|
|
"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 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: `<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>]` (`-<auth-username>` nur relevant, wenn die Authentifizierung des Bezugs `"kind": "pass_trough"` gesetzt ist)
|
|
- 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`
|
|
|