Architektur

Technische Dokumentation. Wo liegen die Daten, wer schreibt worauf, was wann auf die Website kommt. Hintergründe und Begründungen sind hier zu finden:

Die Beispielnamen unten (git.example.org, ableger.example.org) stehen für die Werte, die bei einer eigenen Installation in install.env eingetragen werden (vgl. Getting Started).

Übersicht

flowchart LR
    Leser["Leser*in"]
    Autor["Autor*in"]
    Dev["Entwickler*in (lokal)"]

    subgraph Gitea["Gitea/Forgejo – git.example.org"]
        RepoWeb[("website<br/>Website + CMS-Code")]
        RepoContent[("methoden<br/>Methoden-Inhalte")]
        OAuth["OAuth-Login<br/>Teams read/write/Owners"]
    end

    subgraph Server["Hosting – ein oder zwei Server"]
        ProxyRead["oauth2-proxy<br/>optional, privater Modus"]
        ProxyWrite["oauth2-proxy<br/>optional, privater Modus"]
        Admin["/admin/<br/>Decap CMS"]
        Hook["post-receive Hook"]
        Cron["Cron<br/>alle 10 Min."]
        Sync["sync-methoden.sh"]
        Build["Hugo Build"]
        Website["Website"]
    end

    Leser -->|"prüft Login gegen<br/>(nur privater Modus)"| OAuth
    Autor -->|"prüft Login gegen"| OAuth
    Leser --> ProxyRead --> Website
    Autor --> ProxyWrite --> Admin
    Admin -->|"commit direkt<br/>publish_mode: simple"| RepoContent

    Dev -->|git push origin| RepoWeb
    Dev -->|git push origin| RepoContent
    Dev -.->|"git push deploy<br/>optional, löst sofort aus"| Hook
    Cron -->|ruft auf| Hook

    RepoWeb -->|klont/pullt| Hook
    RepoContent -->|klont/pullt| Sync
    Hook --> Sync
    Hook --> Build
    Sync --> Build
    Build -->|rsync| Website
    Build -->|rsync| Admin

Erläuterungen

Zwei Repos als Grundgerüst:

Der Zugriff auf methoden ist über Decap CMS vorgesehen, kann aber auch direkt über git erfolgen. Der Zugriff auf die Methoden ändert die Inhalte, die Website soll unabhängig davon laufen. Das website-Repo läuft daher unabhängig und kann mit anderen Zugriffsrechten versehen werden. Das website-Repo holt sich die Inhalte aus dem methoden-Repo. Grundsatz: „Der Methoden-Ordner ist die Quelle“.

Zwei oauth2-proxy-Instanzen vor der Website statt einer

Nur im privaten Modus, siehe unten: Website-Ansicht und Redaktion sind unterschiedlich streng zugriffsbeschränkt. Wer schreiben darf, soll auch lesen dürfen, aber nicht umgekehrt (vgl. Schnittstellen, Teil 2).

Der Deploy-Hook liest beide Repos direkt aus Gitea

Läuft der Hook auf demselben Server wie Gitea, geschieht das über einen lokalen Dateipfad. Laufen Gitea und der Deploy-Server getrennt, geschieht das über SSH (vgl. Getting Started, „Ein Server oder zwei“). Damit erreichen auch Commits, die nicht per git push entstanden sind (Giteas Web-Editor, gemergte Pull Requests), zuverlässig die Website.

Sofortiger Push ist Komfort, kein Muss:

Der Cron-Job baut ohnehin regelmäßig den aktuellen Stand neu. Ein optionaler zusätzlicher Git-Remote auf den Deploy-Server löst den Hook nur sofort aus, statt auf den nächsten Cron-Lauf zu warten – so eingerichtet in Getting Started, Schritt 8 (git remote add deploy / git push deploy main).

Der private Modus ist eine reine Infrastruktur-Entscheidung

Die optionalen Zugangsbeschränkungen erfordern keine Änderung an der Repo-Struktur oder Gewohnheit. Ohne die Beschränkung läuft die Website ganz normal öffentlich. Mit Zugangsbeschränkung laufen zwei zusätzliche Prozesse (ProxyRead, ProxyWrite) davor. Beide lassen sich unabhängig voneinander an- und abschalten.

Die vier Bausteine im Überblick

Baustein	Rolle	Warum dieses Werkzeug
Gitea/Forgejo	Speichert beide Repos, verwaltet Zugriffsrechte, stellt OAuth2-Login bereit	Volle Datenhoheit bei Selfhosting, native Fork-/PR-Funktionalität
Decap CMS	Strukturierte Eingabeformulare für Methoden und Varianten	Kein Git-Wissen nötig für Beitragende; committet direkt in das Content-Repo
Hugo	Baut aus den Markdown-Dateien die durchsuchbare, filterbare Website	Schnell, ohne Datenbank/Serverlogik, bildet Zielgruppe/Kompetenzbereich/Kategorie nativ als Taxonomien ab
Pagefind	Volltextsuche über alle gebauten Seiten	Statisches Binary, indiziert das fertige HTML nach dem Hugo-Build, keine eigene Serverkomponente notwendig

Ergänzend, optional:

Baustein	Rolle	Warum dieses Werkzeug
oauth2-proxy	Ermöglicht privaten Modus für Read und/oder Write	Lässt sich ohne Änderung der Strukturen aufschalten, ist eine simple Lösung ohne großen zusätzlichen Aufwand
Pandoc (WASM-Binary, clientseitig)	Ermöglicht das Zusammenfassen von Methoden über Linklisten	Hilft Methoden-Sets zusammenzustellen und lässt sich damit gut in den Entwicklungsprozess von Veranstaltungen einbinden ( vgl. Methoden-Set-Werkzeug).

Fehlender Freigabemodus

Decap CMS bietet die Möglichkeit einen Redaktions-Workflow zu integrieren (Freigeben von Änderungen). Diese Funktionalität lässt sich momentan nicht mit Gitea/ Forgejo abbilden (wäre mit Gitlab vermutlich möglich). Wir haben konzeptionell entschieden, dass dieser Redaktionsworkflow zu viel Kontrolle in die Systematik bringt, zumal die Historie Änderungen transparent und reversibel macht. Außerdem sind wir davon ausgegangen, dass eine feste Community an einem Ableger arbeiten wird und dass ganz öffentliche Instanzen unwahrscheinlich sind. So bleibt das Beitrag einfacher und die Freigabe und Pflege wird zu nicht zu einem technischen Lösungspfad gemacht.