Installation on Ableger

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started

Technische Dokumentation. Eine eigene Ableger-Instanz von den Vorlagen-Repos bis zum ersten funktionierenden Deploy.

Beispielwerte in diesem Text (git.example.org, ableger.example.org, deine-org) stehen für die Werte, die bei einer eigenen Installation tatsächlich verwendet werden.

Ergebnis

Zwei Gitea-Repos: deine-org/website (Website + CMS-Code, aus der Vorlage erzeugt) und deine-org/methoden (Methoden-Inhalte, ebenfalls aus einer Vorlage erzeugt)
Ein Server, der bei jedem Commit (spätestens per Cron) die Website neu baut und veröffentlicht
Eine erreichbare Website unter der eigenen Domain, inklusive /admin/ (Decap CMS) mit funktionierendem Login gegen Gitea

Voraussetzungen

Eine laufende Gitea- oder Forgejo-Instanz mit Owner-Rechten in einer Organisation (alternativ in einem persönlichen Account – außer für den privaten Modus, der zwingend eine Organisation braucht, siehe Schnittstellen, „Voraussetzung: Organisation statt persönliches Konto“)
Ein Server mit Shell-Zugang (SSH), auf dem sich ein eigenes Binary ablegen und ein Cron-Job einrichten lässt
Eine eigene Domain, die auf diesen Server zeigt
Ruby (für die Hilfsskripte) und git auf dem Server

Gitea muss nicht auf dem Deploy-Server liegen. Siehe hierzu weiter unten „Ein Server oder zwei“. Liegt beides auf einem Server, entfällt der SSH-Umweg für den Deploy-Hook.

Architektur

Mon, 01 Jan 0001 00:00:00 +0000

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:

Schnittstellen

Mon, 01 Jan 0001 00:00:00 +0000

Schnittstellen

Technische Dokumentation. Zwei getrennte Themen in einem Dokument, weil beide auf demselben Mechanismus (Gitea-OAuth2) aufbauen.

Decap CMS gegen Gitea anmelden (MUSS)
Privater Modus (KANN) - stellt (einen Teil des Projekts) hinter eine Authentifizierung.

Teil 1: Decap CMS gegen Gitea anmelden (MUSS)

Diese Werte füllen install.env (daraus generiert scripts/generate-config.sh bei jedem Deploy admin/config.yml, siehe Getting Started) und richten zwei serverseitige Voraussetzungen ein, die Decap CMS gegen Gitea zusätzlich braucht. Jeder Fork braucht seine eigene OAuth-Anwendung.

Methoden-Set

Mon, 01 Jan 0001 00:00:00 +0000

Methoden-Set

Technische Dokumentation. methoden-set/ (eigener Top-Level-Ordner im Website-Repo) ist ein eigenständiges, rein clientseitiges Werkzeug: Nutzer*innen fügen Links auf Methoden oder Varianten der Website ein, sortieren sie per Drag & Drop und laden das Ergebnis als Ordner (.zip), als eine zusammenhängende Markdown-Datei oder als Word- oder OpenDocument-Dokument (.docx/.odt, per Pandoc, mit eigener Vorlagen-Auswahl inkl. Upload, optionalem Inhaltsverzeichnis und Kapitelnummerierung) herunter. Läuft vollständig im Browser, keine Serverkomponente und keine Datenübertragung nach außen.

Abhängigkeiten & Updates

Mon, 01 Jan 0001 00:00:00 +0000

Abhängigkeiten & Updates

Technische Dokumentation. Ableger bindet keine Paketmanager-Abhängigkeiten zur Laufzeit ein (keine npm install, kein Bundler). Jede Drittsoftware ist entweder ein einzelnes, direkt vom Hersteller bezogenes Binary, oder eine Handvoll statischer Dateien, die einmalig gezogen und ins jeweilige Repo gelegt werden. Das hält die Installation einfach, bedeutet aber: Updates passieren nicht automatisch, sondern müssen hier bewusst nachgezogen werden.

Software	Aktuell verifizierte Version	Wo verankert	Update-Rezept
Hugo	0.164.0 (reguläre, nicht Extended-Variante)	Fest im Installationsbefehl in Getting Started, Schritt 4 – keine zentrale Versionsdatei	Neue Version bei den Hugo-Releases prüfen, Download-URL in Schritt 4 anpassen, auf dem Server neu ziehen (`~/bin/hugo` ersetzen), danach `hugo version` und einen lokalen Testbuild (`hugo server`) gegen Breaking Changes prüfen (Hugos eigenes CHANGELOG konsultieren)
Pagefind	1.5.2 (musl-Variante, statisch gelinkt)	Fest im Installationsbefehl in Getting Started, Schritt 5	Neue Version bei den Pagefind-Releases prüfen, Download-URL anpassen, `~/bin/pagefind` ersetzen, danach `/suche/` manuell testen (Suchindex wird bei jedem Deploy ohnehin neu gebaut, kein Datenmigrationsschritt nötig)
Decap CMS	3.15.1 (exakt gepinnt, nicht `^3.0.0`)	`<script>`-Tag in `admin/index.html`	Bewusst exakt gepinnt statt einer floatenden Version: Ein automatisches Nebenversions-Update könnte das CMS-Formular ändern, ohne dass das getestet wurde, bevor es live geht. Neue Version bei unpkg.com/decap-cms oder dem Decap-CMS-Repo prüfen, Versionsnummer im Script-Tag anpassen, danach den kompletten Editier-/Speicher-Workflow (Methode und Variante anlegen/bearbeiten) manuell durchklicken
oauth2-proxy	7.15.3	Fest im Installationsbefehl in Schnittstellen, Teil 2	Nur relevant, falls der private Modus genutzt wird. Neue Version bei den oauth2-proxy-Releases prüfen, `~/bin/oauth2-proxy` ersetzen, `supervisorctl restart oauth2-proxy-read oauth2-proxy-write`, danach Login-Flow für beide Instanzen (Website und `/admin/`) neu testen
Pandoc (als WASM-Binary)	pandoc-wasm 1.1.0 → Pandoc 3.10, `@bjorn3/browser_wasi_shim` 0.4.2	`methoden-set/vendor/`	Eigenes Update-Rezept mit einem manuellen Patch-Schritt, siehe Methoden-Set, „Pandoc als WASM-Binary“

Grundsatz für neue Abhängigkeiten

Drittsoftware wird direkt von der offiziellen Quelle bezogen (GitHub-Release, offizielles npm-Paket) statt aus einem anderen, verwandten Projekt vendort – auch wenn eine bereits gelöste, funktionierende Kopie anderswo verfügbar wäre. Das hält die Herkunft jeder Datei nachvollziehbar und macht spätere Updates gegen dieselbe Quelle wiederholbar.