Administration

Für alle, die eine laufende Instanz betreuen (für die Erstinstallation siehe Getting Started).

Anleitung für Admins

Was gibt es zu tun, wo schaut man nach, wenn etwas nicht funktioniert.

Bedarfe

Eine laufende Instanz hat vier Admin-relevante Bereiche:

Bereich	Erreichbar unter	Wofür
Redaktion	`/admin/`	Decap CMS, für alle mit CMS-Zugang – siehe Autor*in
Status-Bereich	`/admin/status/`	Zeigt den letzten Deploy (Erfolg/Fehlschlag, vollständiges Log), Button zum manuellen Auslösen
Deploy-Automatik	läuft serverseitig, kein UI	Cron-Job + Deploy-Hook, siehe Getting Started, Schritt 7
Gitea	`git.<domain>`	Repos, Teams, OAuth2-Anwendungen, CORS, also die eigentliche Zugriffsverwaltung

Als Admin sind vor allem die letzten drei relevant.

Status-Bereich

/admin/status/ zeigt:

Zeitpunkt des letzten Deploys. Ob er erfolgreich war oder fehlgeschlagen ist
Vollständiges Log dieses Laufs, inklusive der Ausgabe von scripts/validate.rb (siehe unten)
Einen Button zum manuellen Auslösen. Nützlich, um nicht bis zu 10 Minuten auf den nächsten Cron-Lauf zu warten, etwa nach einer Änderung an install.env oder einem manuellen Eingriff auf dem Server

Wenn der Button „Fertig“ meldet, aber sich sichtbar nichts ändert

Meist fehlt die Server-Route zum Status-Prozess (siehe Getting Started, Schritt 10) – die Seite selbst lädt zwar, aber der eigentliche Trigger-Aufruf läuft ins Leere.

Ohne privaten Modus ist der Status-Bereich öffentlich erreichbar

(siehe Getting Started) Für die meisten Instanzen unkritisch, aber gut zu wissen, bevor sich jemand über einen fremden Build-Trigger wundert.

Deploy-Ablauf

Kurz zusammengefasst (Details: Getting Started, Schritt 7):

Ein Commit landet in Gitea per git push, über Giteas Web-Editor, über einen gemergten Pull Request, oder über Decap CMS (committet direkt).
Spätestens beim nächsten Cron-Lauf (Standard: alle 10 Minuten) holt der Deploy-Hook den aktuellen Stand beider Repos.
scripts/validate.rb prüft die Methoden-Inhalte gegen die Manifest-Regeln (Teil D). Strukturelle Fehler (kaputte Referenz, doppelte oder nachträglich geänderte Kennung) brechen den Build ab. Die Website bleibt auf dem letzten funktionierenden Stand. Inhaltliche Lücken (fehlendes Pflichtfeld) werden nur gemeldet, blockieren aber nicht.
Hugo baut die Website neu, Pagefind indiziert sie für die Suche.
Alles wird ins Docroot kopiert.
Das Ergebnis (Erfolg oder Fehlschlag, vollständiges Log) landet in status.json, welches unter /admin/status/ angezeigt wird.

Wichtig für die Fehlersuche Ein fehlgeschlagener Build zeigt die Website weiterhin im letzten funktionierenden Zustand. Es geht also nichts offline, neue Änderungen erscheinen nur nicht. Das Log unter /admin/status/ liefert Anhaltspunkte, an welcher Stelle es hakte.

Bekannte Fehlermeldungen

Deploy-Log

Meldung	Bedeutung	Was tun
`Deploy läuft bereits, dieser Lauf wird übersprungen`	Ein Cron-Lauf und ein manueller Trigger (oder zwei Cron-Läufe) haben sich überschnitten. Der Deploy-Hook schützt sich mit einem nicht blockierenden Lock.	Normal, kein Fehler. Der übersprungene Lauf holt beim nächsten regulären Cron-Termin nach.
Ein FEHLER von `validate.rb` (z. B. kaputte Methoden-Referenz, doppelte Kennung, geänderte Kennung)	Strukturverstoß gegen das Manifest Teil D, der Build wird abgebrochen.	Den genannten Eintrag im Content-Repo korrigieren (meist über Gitea direkt, da es sich um einen strukturellen Fehler handelt, den das CMS-Formular normalerweise verhindert). Nach der Korrektur läuft der nächste Deploy wieder normal durch.
Eine WARNUNG von `validate.rb` (z. B. fehlendes Pflichtfeld)	Inhaltliche Lücke bei einem einzelnen Eintrag (Build wird nicht blockiert).	Betroffenen Eintrag bei Gelegenheit über das CMS vervollständigen.

/admin/ → „Login with Gitea“

Meldung	Bedeutung	Was tun
`redirect_uri does not match`	Die in Gitea hinterlegte Redirect-URI der OAuth2-Anwendung stimmt nicht exakt mit der tatsächlich aufgerufenen `/admin/`-URL überein.	In Gitea unter „Anwendungen“ die Redirect-URI prüfen: `https://` korrekt, kein fehlender/zusätzlicher Slash, richtige Domain.
`TypeError: Failed to fetch`, Browser-Konsole zeigt einen CORS-Fehler	CORS ist in Giteas `app.ini` nicht (oder für die falsche Domain) freigeschaltet.	`[cors]`-Block in `app.ini` prüfen, `ALLOW_DOMAIN` muss exakt der Website-Domain entsprechen. Siehe Schnittstellen, Schritt 3.
`Error: invalid empty client secret`	Die OAuth2-Anwendung ist in Gitea als „Confidential Client“ statt „Public Client“ registriert.	In Giteas Datenbank/Oberfläche `confidential_client` auf `0` stellen, oder die Anwendung neu anlegen.
Login-Button erscheint gar nicht	`admin/index.html` fehlt oder das Decap-CMS-Skript lädt nicht.	Erreichbarkeit der Skript-URL prüfen (CDN oder eigene Kopie), Browser-Konsole auf Ladefehler prüfen.

Privater Modus

oauth2-proxy

Meldung	Bedeutung	Was tun
`500` statt `403` bei abgelehntem Login	Bekannte Einschränkung von oauth2-proxy selbst (nicht instanzspezifisch): Team-Ablehnungen werden pauschal mit 500 statt 403 beantwortet. Die Ablehnung selbst funktioniert korrekt.	Log der oauth2-proxy-Instanz prüfen (`Missing Team:"..." from Org:"..."`). Bestätigt, dass es an der Team-Mitgliedschaft liegt, nicht an einem echten Fehler. Details: Schnittstellen.
`cookie_secret must be ... but is 44 bytes`	Das Secret wurde mit `openssl rand -base64` statt `-hex` erzeugt (falsches Kodierungsformat).	Mit `openssl rand -hex 16` neu erzeugen.
`404 page not found` trotz vorhandener Datei	Bei `file://`-Upstreams fehlt der `#/`-Fragment-Teil in der Konfiguration.	`upstreams`-Zeile in der `.cfg`-Datei um `#/` ergänzen.
`NOT OK, wrong interface (127.0.0.1)` bei `uberspace web backend set`	`http_address` bindet nur auf `127.0.0.1` statt `0.0.0.0`.	In der `.cfg`-Datei auf `0.0.0.0:<port>` ändern.
`upstream ids/paths must be unique`	Zwei per URL-Fragment unterschiedene Upstreams (`file://` + `http://`) in einer flachen `upstreams = [...]`-Liste. Kann von oauth2-proxy nicht wie erwartet aufgelöst werden.	Nicht versuchen, zwei Upstreams in einer Instanz zu kombinieren. stattdessen einen Upstream verwenden, der selbst beide Aufgaben übernimmt (siehe `admin-status-server.rb`, das selbst auch statische Dateien ausliefert).

Sonstiges

Meldung	Bedeutung	Was tun
`sha not found` (400) beim Speichern im CMS	Gitea-Eigenheit bei Nicht-ASCII-Zeichen (Umlaute) im Datei-/Ordnerpfad. Tritt auch bei bereits bestehenden Einträgen auf, nicht nur bei neuen.	Slug/Ordnername auf ASCII umstellen (ü→u, ä→a usw.). `slug.clean_accents: true` ist bereits global gesetzt, verhindert das Problem für neue Einträge. Bestehende umlauthaltige Ordner müssen einmalig manuell umbenannt werden.
`cannot load such file -- webrick` beim Start des Admin-Status-Servers	Ruby ≥ 3.0 hat `webrick` nicht mehr in der Standardbibliothek.	`gem install --user-install webrick` auf dem Server nachholen.
Status-Seite zeigt dauerhaft „noch kein Deploy-Status vorhanden“, obwohl Deploys laufen – oder der Trigger-Button löst sichtbar den falschen Build aus	Läuft auf demselben Account noch ein anderes Deployment mit ähnlichem Bare-Repo-Namen (z. B. eine zweite Ableger-Instanz), leitet `admin-status-server.rb` Status-Datei und Hook-Pfad standardmäßig aus `WEBSITE_REPO` ab – das kann mit dem anderen Deployment kollidieren.	`DEPLOY_STATUS_FILE`/`DEPLOY_HOOK_PATH` in `install.env` explizit auf eindeutige Pfade setzen, siehe Getting Started, „Mehrere Ableger-Instanzen auf einem Account“.

Zusammenhänge mit Gitea

Wenn etwas nicht funktioniert, hilft es zu wissen, welche Gitea-Einstellung wofür zuständig ist:

Zwei Repos (website, methoden)

Getrennte Zugriffsrechte. Wer nur Methoden bearbeiten soll, braucht nur Zugriff auf methoden. Verwechslungen hier sind die häufigste Ursache für „warum kann diese Person nicht committen“ oder „warum sieht diese Person den Website-Code“.

OAuth2-Anwendung für Decap CMS

Ein Public Client (kein Secret), Redirect-URI exakt https://<domain>/admin/. Betrifft nur den Login in /admin/, nicht den privaten Modus (siehe unten).

CORS-Freigabe in app.ini

Ohne sie schlägt der Login in /admin/ mit einem Browser-seitigen Fehler fehl, unabhängig davon, ob die OAuth2-Anwendung korrekt konfiguriert ist. Leicht zu übersehen, weil die Fehlermeldung („Failed to fetch“) nicht offensichtlich auf CORS hindeutet.

Deploy Key

Nur bei getrenntem Gitea-/Deploy-Server, siehe Getting Started, „Ein Server oder zwei“ Ein reiner Lesezugriff je Repo, ausschließlich für den Deploy-Hook. Kein Zusammenhang mit CMS-Zugriffsrechten.

Teams read/write/Owners

Ist nur relevant, wenn der private Modus aktiv ist (siehe Schnittstellen, Teil 2). write/Owners dürfen auch lesen, das ist Absicht, keine Fehlkonfiguration.

Zwei getrennte OAuth2-Anwendungen für den privaten Modus

Eine für die Website-Ansicht, eine für /admin/, mit unterschiedlichen Redirect-URIs. Diese sind nicht dieselbe Anwendung wie die für Decap CMS: Decaps Anwendung ist ein Public Client ohne Secret, die beiden oauth2-proxy-Anwendungen sind Confidential Clients mit Secret. Werden diese verwechselt, schlägt der Login auf die eine oder andere Art fehl.

Wenn eine Person die Institution verlässt

Zugriff entziehen heißt: Person aus dem/den zuständigen Gitea-Team(s) entfernen (write für CMS-Zugang, ggf. zusätzlich read/Owners je nach Setup). Wer überhaupt Zugang bekommt ist eine bewusste Prozessentscheidung der Instanz, keine Softwarefunktion. Ein eigener Deprovisioning-Mechanismus existiert nicht und ist auch nicht vorgesehen, da Gitea-Bordmittel dafür ausreichend sind.