core/readme.md

davina

Beschreibung

• bereitet rohe Kalender-Daten aus verschiedenen Quellen mittels CalDAV auf und stellt diese als Server bereit
• basiert auf sabre/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)
• Web-Server neustarten

Dokumentation

Der grobe Aufbau einer Konfigurations-Datei lässt sich in der Beispiel-Konfiguration 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:

"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:

"auth": {
	"kind": "static",
	"data": {
		"password": "secret"
	}
}

Durchleiten

Es wird kein bestimmtes Passwort erwartet; statt dessen wird d eingegebene Passwort an den Aufruf der Quelle weitergeleitet. Beispiel:

"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-Format ics im Netz abrufbar sind, können wie folgt eingebunden werden:

"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 lokal über Port 8000 aus, würden diese Werte lauten:

• Kalender-URL: http://localhost:8000/calendars/-/holidays
• Nutzername: holidays
• Passwort: secret