dorfteich/docs/de/manual/site-admin-guide.md

Site-Admin-Handbuch

Englisches Original: docs/manual/site-admin-guide.md

Wie du eine Dorfteich-Instanz aus dem Browser verwaltest. Installation, Updates und Betrieb auf Host-Ebene behandelt das Self-Hosting-Handbuch (englisch); hier geht es um die beiden Admin-Seiten: Admin → Einstellungen (/admin) und Admin → System (/admin/system).

Ein Site-Admin sieht und darf alles — nutze für die tägliche Arbeit ein normales Konto.

Erster Kontakt: der Einrichtungsassistent

Eine frische Instanz begrüßt dich mit einem Assistenten in sechs Schritten: Sprache → das Site-Admin-Konto → Instanzname und Standardsprache → SMTP-Relay (mit Live-Testmail; überspringbar) → Registrierungsmodus → fertig. Bis er abgeschlossen ist, antwortet die Instanz auf alles mit 503 setup_required. Unbeaufsichtigte Installationen befüllen den Assistenten vorab über SETUP_ADMIN_*-Umgebungsvariablen.

Admin → Einstellungen

Instanz

• Name (erscheint in der Kopfleiste und in Mails) und Standardsprache (gilt für anonyme Besucher und server-gerenderte Seiten).
• Registrierungsmodus: open (jeder darf sich registrieren, mit E-Mail-Bestätigung) oder closed (nur bestehende Konten melden sich an).

Kontingente

Instanzweite Standardwerte: Bearbeiter/Leser pro Teich, zusätzliche geteilte Teiche pro Person (Standard 0 — erhöhe ihn oder vergib Pro-Person-Overrides, damit Leute gemeinsame Teiche anlegen können), Speicher pro Teich, maximale Dateigröße. Der Kontingent-Manager darunter setzt Overrides pro Person/Teich, die die Standardwerte überstimmen.

Uploads

Die Allow-Liste der Nicht-Bild-Dateiendungen, die Nutzer anhängen dürfen, und die SVG-Richtlinie (sanitize entfernt Skripte aus hochgeladenen SVGs, reject lehnt sie ab).

Öffentliche API und MCP

Zwei unabhängige Hauptschalter, beide standardmäßig aus:

• Öffentliche REST-API: erlaubt Nutzern, persönliche API-Tokens anzulegen und /api/public/v1 zu verwenden (siehe das API-Handbuch).
• Eingebauter MCP-Endpoint: stellt /api/mcp für KI-Assistenten bereit (MCP-Handbuch).

Keiner der Schalter wirkt allein pro Teich — jeder Teich stimmt zusätzlich über seine Teich-Einstellungen zu. Aus heißt: Die Endpoints antworten mit 404.

Rechtsseiten

Impressum und Datenschutzerklärung als Markdown, veröffentlicht unter /legal/imprint und /legal/privacy und aus jeder Fußzeile verlinkt. Eine Vorlage mit Prüf-Checkliste liegt in docs/self-hosting/legal-template.md. Bis sie konfiguriert sind, zeigen die Seiten einen Hinweis (und dir ein Warnbanner).

Backups

Siehe Admin → System → Backups unten.

Plugins

Installiere Plugins per ZIP-Upload (alternativ: das ZIP in den _dropzone/-Ordner auf dem Plugins-Volume legen — ein Watcher installiert es binnen Sekunden und verschiebt abgelehnte Pakete mit Begründung nach _quarantine/).

Jedes installierte Plugin hat einen Instanz-Modus:

Modus	Bedeutung
disabled	überall inaktiv (der Standard nach dem Installieren)
optional	Teich-Admins entscheiden pro Teich
required	in jedem Teich aktiv, kein Opt-out

Jedes Plugin hat eine gesandboxte Vorschau-Seite zum Ausprobieren vor dem Aktivieren. Deinstallieren ist blockiert, solange ein Plugin required ist; Dokumente behalten ihre Plugin-Blöcke in jedem Fall und zeigen den Fallback-Text des Plugins, wenn es fehlt.

Mitgelieferte Referenz-Plugins: toc (Inhaltsverzeichnis), page-index (label-gefilterte Seitenliste), mermaid (Diagramm-Blöcke), drawio (vollwertiges draw.io-Bearbeiten), section-styles-basic (farbige Hinweiskästen).

Woher kommen die ZIPs der Referenz-Plugins? Sie liegen den Server-Images nicht bei — sie werden aus dem Repository gebaut (Node 22

• pnpm, einmalig pnpm install im Repo-Wurzelverzeichnis):

cd packages/plugins/<name>   # toc | page-index | mermaid | drawio | section-styles-basic
pnpm build                   # → dist/<id>-<version>.zip — diese Datei hochladen

Der drawio-Build lädt beim ersten Lauf sein gepinntes Editor-Bundle von GitHub und packt ein ~27-MiB-ZIP (innerhalb des 64-MiB-Limits für Plugin-Uploads); die anderen vier bauen offline in Sekunden.

Typischer Ablauf: ZIP hochladen, die abgeschottete Vorschau prüfen, den Instanz-Modus auf optional stellen und das Plugin dann je Teich aktivieren (Teich-Einstellungen → Plugins — in persönlichen Teichen macht das der Eigentümer selbst).

Personen

Die Personenverwaltung: Konten suchen, deaktivieren/aktivieren, Bestätigungsmails erneut senden, Site-Admins ernennen/absetzen und Konten löschen. Die Löschung bietet Pseudonymisierung an: Das Konto und seine persönlichen Daten verschwinden, aber geteilte Inhalte überleben, einem neutralen Platzhalter zugeschrieben. Schutzmechanismen verhindern, dich selbst zu deaktivieren oder den letzten Site-Admin zu entfernen.

Admin → System

Der Blick des Betreibers auf einen Schirm:

• Wartungsjobs: jeder Wartungsjob (Papierkorb-Bereinigung, Versions-Ausdünnung, Seiten-Kompaktierung, Datenexport-Bereinigung, Benachrichtigungs-Digests) mit Takt, letztem Lauf, Dauer und Ergebnis — plus manuellem Ausführen-Knopf (selbst audit-geloggt).
• Backups: Die Status-Karte spiegelt den letzten Lauf des Sidecars und sein Frische-Urteil, mit einem Jetzt sichern-Knopf. Darunter:
  • Backup-Einstellungen: lokale Aufbewahrung (überstimmt den Container-Standard) und das Nextcloud-Ziel — Server-Adresse, Benutzername, App-Passwort (liegt im dateibasierten Secret-Store auf dem Secrets-Volume, nie in der Datenbank), Ordner, Upload-Zeitplan (nach jedem Backup / wöchentlich / manuell), entfernte Aufbewahrung und ein Verbindung testen-Knopf, der die Zugangsdaten prüft und den Ordner anlegt.
  • Wiederherstellung: listet lokale und Nextcloud-Sets; beim Wiederherstellen tippst du die Backup-ID zur Bestätigung ein, dann geht die Instanz in den Wartungsmodus, stellt sich wieder her und startet neu. Alles Weitere zu Backups (Spiegel auf einen privaten Host, Disaster Recovery) steht im Self-Hosting-Handbuch und im Restore-Runbook (beide englisch).
• Audit-Log: administrative und Auth-Ereignisse (Zugriffsregeln, Mitglieder, Personenverwaltung, Kontingente, Plugins, Einstellungen, Einrichtung, Tokens, API-Schreibzugriffe, Backup-Aktionen) mit Filtern nach Akteur/Aktion/Zeit, 50 pro Seite.
• Speicher: die zwanzig größten Teiche und die Instanz-Summe.

Health, Monitoring, Go-Live

• GET /api/v1/readyz ist die Eigendiagnose der Instanz; überwache sie (Down-vs.-Degraded-Semantik und ein fertiges Monitor-Set: deploy/monitoring.md).
• Go-Live-Checkliste für eine frische Produktionsinstanz: deploy/go-live.md.