Betriebsreferenz
Auf dieser Seite

Terminverwaltung betreiben

Für den Arbeitsablauf von der ersten Übergabe bis zur Wiederherstellung gibt es die Nutzungsanleitung für den Serverbetrieb. Die folgenden Abschnitte ergänzen sie um Konfigurationswerte, Befehle und technische Grenzen. Den Einstieg für andere Aufgaben findest du im Wegweiser zu allen Anleitungen.

Lokal starten

Nach make build oder mit einem passenden Releaseprogramm Start.command auf dem Mac oder ./Start.sh unter Linux starten. Ein vorhandenes bin/terminverwaltung aus make build hat Vorrang vor einem plattformspezifischen Releaseprogramm; zum Wechsel auf ein Release das lokale Programm entfernen oder das gewünschte Programm direkt starten. Danach http://127.0.0.1:8080 verwenden. localhost ist eine andere Adresse; Browseradresse und konfigurierte öffentliche URL müssen übereinstimmen.

Bei der ersten Einrichtung gibt das Terminal ein Token aus. Damit auf der Webseite den Namen und das Adminpasswort festlegen. Danach meldet sich die Administration ausschließlich mit diesem Passwort an. Mitglieder werden über persönliche Einrichtungslinks freigeschaltet. Es gibt keine Standardzugangsdaten und kein Mailsystem.

Mit Strg+C geordnet beenden. Derselbe Startbefehl verwendet beim nächsten Mal die vorhandenen Daten. Nur eine Instanz darf denselben Datensatz öffnen. Der private Datenordner darf nicht als Webseite ausgeliefert werden.

Konfiguration

.env.example nach .env kopieren und benötigte Werte setzen. Der native Server liest die Datei wörtlich, ohne Shell-Ausführung; gesetzte Umgebungsvariablen haben Vorrang.

Variable Bedeutung
APP_PUBLIC_URL Genaue Browseradresse; Standard http://127.0.0.1:8080
APP_ADDR Bind-Adresse; Standard 127.0.0.1:8080
APP_DATA Privater Datenordner; Standard ./data-lite
APP_SETUP_TOKEN Optional eigenes Token für die erste Einrichtung
APP_DOMAIN Domain für die beiliegende Caddy-/Compose-Konfiguration
APP_PATH_AUTH_PATHS Optional: kommagetrennte Pfade für zusätzlichen Passwortschutz
APP_PATH_AUTH_USER Benutzername für den Pfadschutz
APP_PATH_AUTH_PASSWORD Passwort für den Pfadschutz, mindestens 12 Zeichen

Für den Übergang werden FF_ADDR, FF_PUBLIC_URL, FF_DATA und FF_SETUP_TOKEN als Rückfallwerte unterstützt, auch aus einer älteren .env; der jeweils nicht leere APP_-Wert hat Vorrang. Für Compose muss weiterhin APP_DOMAIN gesetzt werden. Alternativ lassen sich -addr, -public-url und -data als Programmargumente übergeben. ./Start.sh -version zeigt die Version. Für Mac kann bei allen folgenden Befehlen auch ./Start.command verwendet werden.

Zusätzlicher Passwortschutz für Pfade

Unter Verwaltung → Einstellungen → Passwortschutz für Pfade können Pfade, Benutzername und Passwort eingerichtet werden. Ein Pfad pro Zeile schützt auch dessen Unterpfade. Das Passwort wird als Hash im Datensatz und in dessen Sicherungen gespeichert und später nicht angezeigt. Das bisherige Passwort bleibt erhalten, wenn das Passwortfeld beim Ändern leer bleibt. Der Schutz wird sofort wirksam; gegebenenfalls sind die neuen Zugangsdaten unmittelbar für Verwaltung und Feeds erforderlich.

Alternativ lässt sich der Schutz über Umgebungsvariablen vorgeben. Diese Konfiguration hat vollständig Vorrang und kann nicht im Admin-Menü geändert werden. Beispiel in .env:

APP_PATH_AUTH_PATHS=/api/admin,/calendar/public.rss
APP_PATH_AUTH_USER=verein
APP_PATH_AUTH_PASSWORD=ein-langes-individuelles-passwort

Das Beispielpasswort durch ein langes, zufälliges eigenes Passwort ersetzen. Alle drei Werte müssen gemeinsam gesetzt sein; eine fehlerhafte oder unvollständige Konfiguration verhindert den Serverstart. Änderungen an Umgebungsvariablen werden beim Neustart wirksam. Diese Schutzdaten liegen in der Umgebung beziehungsweise in .env im Klartext und sind nicht Teil der Anwendungssicherung. .env vertraulich halten, etwa mit chmod 600 .env. Bei Docker Compose werden diese Variablen an den Dienst weitergegeben; die Compose-Interpolation von Sonderzeichen wie $ beachten.

Ein Eintrag schützt genau den Pfad und seine Unterpfade: /api/admin erfasst etwa /api/admin/settings, aber nicht /api/administrator. / schützt die gesamte Anwendung, auch Feeds und Gesundheitsprüfung. Ungeschützte Pfade bleiben frei zugänglich. Nach 20 fehlgeschlagenen Versuchen innerhalb von 15 Minuten kann der Zugang vorübergehend begrenzt sein; hinter einem Reverse-Proxy können mehrere Besucher dieselbe Quelladresse teilen.

Der Pfadschutz ist eine zusätzliche Schranke und ersetzt keine Mitgliedersitzung oder Leitungsberechtigung. Er schützt nur die angegebenen HTTP-Pfade: Eine geschützte Browserseite sperrt nicht automatisch die zugehörigen APIs oder Kalenderfeeds. Wer etwa Termininhalte schützen möchte, muss auch die entsprechenden /api/events- und /calendar-Pfade berücksichtigen. Je nach Anwendung können /api/bootstrap und weitere Endpunkte ebenfalls Angaben ausliefern. Öffentlich geschaltete Termine sollten daher weiterhin nur für tatsächlich öffentliche Inhalte verwendet werden.

Basic-Zugangsdaten werden bei Anfragen mitgesendet. Für den gemeinsamen Betrieb HTTPS vom Browser bis zum vertrauenswürdigen Reverse-Proxy verwenden und den Backendzugang auf ein privates Netz beschränken. Kalender- und RSS-Clients müssen Basic Authentication unterstützen, wenn ihre Feedpfade geschützt sind. Überprüfe nach Änderungen sowohl den Zugriff ohne als auch mit Zugangsdaten und die betroffenen Links.

Falls die im Admin-Menü gespeicherten Pfadschutzdaten verloren gehen, den Dienst stoppen und ./Start.sh -reset-path-auth ausführen. Dadurch wird nur der im Datensatz gespeicherte Pfadschutz entfernt; ein über Umgebungsvariablen konfigurierter Schutz bleibt bestehen und muss dort geändert werden. Anschließend den Dienst neu starten.

Server mit HTTPS

Für einen vorhandenen Apache gibt es die folgende native Einrichtung. Der Compose-Abschnitt weiter unten beschreibt den Betrieb mit Caddy.

Linux-Binary hinter Apache

Die Vorlagen sind für Apache 2.4 und systemd auf Debian oder Ubuntu eingerichtet. termine.ettling.eu muss per DNS auf den Server zeigen und über die öffentlichen Ports 80 und 443 erreichbar sein. Apache leitet HTTPS-Anfragen an 127.0.0.1:8094 weiter. Prüfe auf dem Server mit sudo ss -ltn 'sport = :8094', ob dieser Port frei ist. Bei Bedarf ändere den Port im systemd-Dienst und im HTTPS-vHost gemeinsam.

Binary bauen und übertragen. Führe auf dem Linux-Server uname -m aus. Baue anschließend im Projektverzeichnis auf deinem Rechner die passende Datei, zum Beispiel für x86_64:

make build-linux-amd64
scp bin/terminverwaltung-linux-amd64 benutzer@server:~/terminverwaltung

Für aarch64 bzw. arm64 verwende make build-linux-arm64 und bin/terminverwaltung-linux-arm64. make build-linux baut beide Varianten. Wähle für den Upload genau eine Datei. Sie enthält Webseite, Hilfe, Zeitzonendaten und die eingebettete Datenbankbibliothek. Für den Betrieb genügen das Binary und die vorhandenen Systemdienste. Externe HTTPS-Kalenderfeeds nutzen den CA-Zertifikatsspeicher des Servers.

Dienst installieren. Auf dem Server einmalig das Dienstkonto anlegen und das Binary installieren:

sudo useradd --system --user-group --no-create-home \
  --home-dir /var/lib/terminverwaltung --shell /usr/sbin/nologin terminverwaltung
sudo install -o root -g root -m 0755 "$HOME/terminverwaltung" /usr/local/bin/terminverwaltung
sudoedit /etc/systemd/system/terminverwaltung.service

Füge in die geöffnete Datei den Inhalt von deploy/systemd/terminverwaltung.service ein. Der Dienst legt /var/lib/terminverwaltung mit Modus 0700 für Datenbank und Sicherungen an. Anschließend starten und lokal prüfen:

sudo systemctl daemon-reload
sudo systemctl enable --now terminverwaltung
curl -fsS -H 'Host: termine.ettling.eu' http://127.0.0.1:8094/healthz

Domain und Zertifikat einrichten. Lege zuerst den HTTP-vHost an. Kopiere dafür den Inhalt von deploy/apache/termine.ettling.eu.conf in die mit sudoedit geöffnete Datei:

sudo a2enmod proxy proxy_http headers rewrite ssl
sudo install -d -m 0755 /var/www/termine.ettling.eu/.well-known/acme-challenge
sudoedit /etc/apache2/sites-available/termine.ettling.eu.conf
sudo a2ensite termine.ettling.eu.conf
sudo apache2ctl configtest && sudo systemctl reload apache2

Der HTTP-vHost bedient Anfragen für die ACME-Challenge aus dem Webroot und leitet die übrigen Anfragen an die feste HTTPS-Adresse weiter. Mit dem vorhandenen Certbot ein Zertifikat für die Domain ausstellen:

sudo certbot certonly --webroot -w /var/www/termine.ettling.eu \
  --cert-name termine.ettling.eu -d termine.ettling.eu \
  --deploy-hook 'systemctl reload apache2'

Kopiere anschließend den Inhalt von deploy/apache/termine.ettling.eu-le-ssl.conf in die zweite Apache-Datei:

sudoedit /etc/apache2/sites-available/termine.ettling.eu-le-ssl.conf
sudo a2ensite termine.ettling.eu-le-ssl.conf
sudo apache2ctl configtest && sudo systemctl reload apache2
curl -fsS https://termine.ettling.eu/healthz
sudo certbot renew --cert-name termine.ettling.eu --dry-run

Der HTTPS-vHost reicht den ursprünglichen Host weiter, damit die Anwendung ihn gegen ihre öffentliche URL prüfen kann. Apache setzt X-Real-IP auf die IP der direkt verbundenen Gegenstelle. Der Dienst vertraut diesem Header über -trust-loopback-proxy ausschließlich auf Loopback-Verbindungen, damit Anfragelimits pro Client gelten. Der App-Port bleibt an Loopback gebunden.

Beim ersten Start steht das Einrichtungstoken im Dienstjournal (sudo journalctl -u terminverwaltung -b). Öffne https://termine.ettling.eu und richte damit den Adminzugang ein. Für spätere Updates genügt der Upload des neuen Binarys. Stoppe den Dienst, sichere den Datensatz, installiere das neue Binary am selben Pfad und starte den Dienst wieder.

Caddy und Docker Compose

Für die eigene Domain DNS auf den Server zeigen lassen; im Beispiel wird termine.beispiel-verein.de verwendet. Für Caddy werden die öffentlichen Ports 80 und 443 benötigt. In .env setzen:

APP_DOMAIN=termine.beispiel-verein.de
APP_PUBLIC_URL=https://termine.beispiel-verein.de

Dann im Paketordner:

docker compose -f compose.yaml -f compose.domain.yaml up -d --build
docker compose -f compose.yaml -f compose.domain.yaml logs app

Das Einrichtungstoken steht beim ersten Start im Anwendungslog. Caddy übernimmt HTTPS und leitet intern an den Dienst weiter. Daten liegen im Docker-Volume app-data; zusätzlich legt Caddy eigene Volumes für Zertifikate an. Zum lokalen Compose-Betrieb ohne öffentliche Domain genügt docker compose up -d --build.

Docker-/Compose-Dateien liegen bei; ein Containerbuild wurde nicht verifiziert. Öffentliche HTTP-Adressen lehnt die Anwendung ab.

Terminfeeds und Aktualisierung

Eine HTTPS- oder webcal-Adresse für einen unterstützten Terminfeed beim jeweiligen Kalenderanbieter kopieren: für öffentliche Kalender eine öffentliche Adresse, für interne Kalender eine private Adresse. Bei Google Kalender findet man sie unter Einstellungen → Kalender integrieren. Auch Adressen mit Query-Parametern oder ohne .ics-Endung sind möglich. webcal:// wird beim Abruf zu HTTPS. Eine Kalender-Webseite oder heruntergeladene ICS-Datei ist kein abonnierbarer Feed.

Die Anwendung meldet sich nicht per OAuth oder Passwort beim Anbieter an. Der Feed muss mit seiner Adresse lesbar sein; Schreibrechte für die Terminpflege werden beim Anbieter vergeben. Private Quelladressen werden nicht als Quellfeld an Mitglieder oder deren Abos ausgegeben. Bekannte Darstellungen konfigurierter Feedadressen werden beim Import aus Termintexten entfernt; dennoch sollten vertrauliche URLs nicht in Titel, Ort oder Beschreibung eingetragen werden. Eine private Feedadresse kann ein Zugriffstoken enthalten und ist wie ein Passwort zu behandeln.

Der Abruf verwendet nur öffentlich erreichbare Ziele, keine HTTP-Proxys und maximal fünf HTTPS-Weiterleitungen. Private und lokale Netzwerkadressen sowie unverschlüsseltes HTTP werden abgewiesen; reine CalDAV-Zugänge mit Anmeldung werden nicht unterstützt.

Der Server ruft aktive Quellen nach dem Start und standardmäßig alle fünf Minuten ab. Die Administration kann das Intervall auf 1 bis 1440 Minuten und den Übernahmezeitraum auf 1 bis 365 Tage zurück und 1 bis 60 Monate voraus einstellen; die bisherigen Standardwerte sind 90 Tage und 18 Monate. Änderungen gelten ohne Neustart. Zusätzlich ist ein manueller Abgleich möglich. JSON- und CSV-Feeds sowie Schema.org-JSON-LD beschreiben einzelne Termine; Beispiele und das genaue Schema stehen unter Terminformate. Serien, Ausnahmen und verschobene Einzeltermine werden innerhalb des unterstützten Umfangs verarbeitet. Nicht unterstützte oder unvollständig lesbare Regeln führen zu einem Fehler statt zu einem teilweisen Import. Der bisherige Bestand bleibt erhalten.

Bei Abruffehlern Feedadresse, Freigabe beim Anbieter und Netzwerk prüfen. Fehleranzeigen enthalten keine Quelladresse. Ein bewusst gelöschter Termin wird nicht automatisch zur Absage: Für klare Absagen den Termin mit ABGESAGT: im Titel erhalten. Quelle/Sichtbarkeit eines gefüllten Kalenders durch Deaktivieren und Neuanlegen korrigieren.

Kalender-Apps können ältere Daten zwischenspeichern. Auch eine gesperrte Freigabe löscht bereits heruntergeladene Termine nicht aus fremden Geräten. Kurzfristige Änderungen weiterhin persönlich oder über den vereinbarten Gruppenchat mitteilen.

Sicherung und Wiederherstellung

Automatische Sicherungen liegen unter data-lite/backups. Der aktuelle UTC-Tagesstand wird beim Start und stündlich ersetzt; höchstens 14 Tagesarchive bleiben erhalten. Diese Kopien liegen auf demselben Datenträger: regelmäßig zusätzlich auf ein anderes Gerät sichern.

Sicherungen sind vollständige unverschlüsselte JSON-Dateien mit Namen, Antworten, Passwort-Hashes und vertraulichen Feedadressen. Der native Server erzeugt sie mit Dateirechten 0600; der Datenordner benötigt 0700. Ein Browserdownload unter Verwaltung enthält dieselben vertraulichen Inhalte und muss ebenfalls geschützt aufbewahrt werden. Es wird kein zusätzlicher Schlüssel zur Wiederherstellung benötigt.

Für Offline-Kommandos die laufende Instanz vorher stoppen:

./Start.sh -backup /sicherer/pfad/termine.json
./Start.sh -data ./wiederhergestellt -restore /sicherer/pfad/termine.json
./Start.sh -data ./wiederhergestellt -check

Restore akzeptiert ausschließlich einen leeren Zieldatensatz und prüft das Lite-Datenformat. Vorhandene Konten, Gruppen, Termine und Antworten werden übernommen. Alle Sitzungen, noch offenen Einrichtungslinks, persönlichen Abotokens und Gast-Einladungslinks zu Abstimmungen werden entwertet. Gaststimmen bleiben erhalten; die Verantwortlichen müssen bei Bedarf neue Gastlinks erstellen. Mitglieder müssen danach neue Zugänge und Abos erhalten. Bei einem Domainwechsel auch bestehende öffentliche Abos neu einrichten.

Adminpasswort vergessen

Dienst stoppen und im privaten Terminal ausführen:

./Start.sh -reset-admin

Das neue Passwort über die Standardeingabe eingeben, mit Enter abschließen und anschließend normal starten. Die Eingabe wird aktuell im Terminal angezeigt; nur in einer privaten Sitzung verwenden. Das Passwort nicht als Kommandozeilenargument oder in die Shell-History schreiben. Bestehende Adminsitzungen werden entwertet.

Aktualisieren und Grenzen

Dienst stoppen, eine vollständige Sicherung erstellen, Programmdateien ersetzen und mit demselben APP_DATA starten. Für ein Release mit verändertem Datenformat zuerst dessen Hinweise lesen.

Diese Version verwendet terminverwaltung/v1 und standardmäßig den Ordner data-lite. Beim Start oder bei einem Offline-Kommando wird ein vorhandener Datensatz ff-ettling.db im selben Datenordner übernommen, wenn die neue terminverwaltung.db noch keinen Snapshot enthält. Die alte Datenbank bleibt unverändert. Gruppen, Konten, Termine, Antworten und bestehende Zugänge bleiben dabei erhalten. Vor dem Update die alte Instanz stoppen und eine vollständige Sicherung erstellen. Alte und neue Version nach der Übernahme nicht parallel betreiben: Sie verwenden getrennte Datenbanken und ihre Daten würden auseinanderlaufen.

Auch JSON-Sicherungen im Format ff-ettling-lite/v1 können in einen leeren Datenordner wiederhergestellt werden. Wie bei jeder Wiederherstellung werden Sitzungen, offene Einrichtungslinks und persönliche Abos dabei entwertet. Andere frühere tinyTreff-Datenformate werden nicht automatisch übernommen.

Betriebsmodell: ein Prozess, privater lokaler Datenträger, tinySQL mit höchstens 16 MiB Anwendungszustand. Quellen und Zugangsdaten bleiben beim Betreiber. Die Webseite benötigt eine Onlineverbindung. Mac-Programme sind nicht signiert/notarisiert; macOS-Freigaben selbst prüfen. Der Prüfbericht beschreibt einen historischen Stand der früheren FF-Ettling-Version; seine Ergebnisse gelten nicht automatisch für spätere Änderungen.