Knowledgebase

Dokumentation des Netzwerks der Beleuchtungs- und Videoabteilung der Staatsoper Hamburg. Dieses Repo ist das Obsidian-Vault (content/) und gleichzeitig das Quartz-Projekt, das daraus die statische Website baut.

Mitarbeiten

1. content/ als Vault in Obsidian öffnen.
2. Für neue Notizen die passende Vorlage aus content/Templates/ kopieren.
3. Neue Notiz immer in der index.md ihres Ordners verlinken, sonst taucht sie im Graph als Waise auf.
4. Frontmatter-Felder wie in den Vorlagen vorgegeben ausfüllen (type, bereich, status, description) — die Bases-Register hängen von konsistenten Properties ab.
5. Commit + Push nach main → Forgejo Action prüft, dass der Build funktioniert; Komodo zieht auf dem VPS per Webhook automatisch nach (siehe unten).

Mitgelieferte Obsidian-Plugins (in .obsidian/plugins/, beim ersten Öffnen aktivieren): Dataview, Templater, Tasks, Obsidian Git.

Lokal bauen / Vorschau

npm ci
npx quartz plugin install --from-config
npx quartz build --serve

Seite läuft dann auf http://localhost:8080.

Deployment

Pull-basiert über Komodo, nicht Push aus der CI. .forgejo/workflows/build-check.yml baut bei jedem Push nach main nur zur Validierung (schlägt fehl, wenn Config/Content kaputt sind) — deployt aber nichts. Der eigentliche Deploy läuft über eine Komodo-Repo-Resource auf dem VPS: Forgejo ruft per Webhook bei jedem Push den Komodo-Webhook auf, Komodo pullt main und führt danach den on_pull-Hook aus:

npm ci
npx quartz plugin install --from-config
npx quartz build
mkdir -p /home/nross/site
rsync -a --delete public/ /home/nross/site/

Grund für Pull statt Push aus der CI: der VPS ist nur über Netbird erreichbar, und der Forgejo-act_runner entfernt seit Version 3.0 (Fix für CVE-2026-58053) automatisch alle --cap-add/--device-Optionen aus Workflow-Containern, außer der ganze Runner läuft privilegiert. Damit lässt sich Netbird (braucht NET_ADMIN für das WireGuard-Interface) nicht mehr sauber scoped im CI-Job betreiben. Komodos Periphery-Agent läuft dagegen mit normalen Rechten direkt auf dem VPS-Host, außerhalb jeder Container-Sandbox — dort klappt der Build/Deploy problemlos.

Keine Forgejo-Secrets mehr nötig für den Deploy-Teil — build-check.yml braucht keine.

Historisch: Zwei frühere Ansätze wurden verworfen: (1) Push-Deploy aus der CI mit Netbird-Join im Job-Container + dediziertem sshd/rrsync-Deploy-User auf Port 2222 — scheiterte am obigen Capability-Problem; (2) ein Cronjob-basierter Pull direkt auf dem VPS — durch Komodos Webhook-getriebenen Repo/on_pull-Mechanismus ersetzt (sofortiger Trigger statt Polling, plus UI/Logs/History). Die für (1) angelegten VPS-Artefakte (deploy-kb-User, /etc/ssh/sshd_config.d/deploy-netbird.conf, iptables-Regel, SELinux-Port-Label) sind ungenutzt und können bei Gelegenheit aufgeräumt werden.

Struktur

Der Vault ist nach Art der Information gegliedert, nicht nach Thema. Das beantwortet beim Schreiben die Frage „wo gehört das hin?" und beim Lesen die Frage „wo suche ich das?".

content/
├── index.md          Einstieg nach Anliegen ("Was möchtest du tun?")
├── Start/            Lernpfad, Glossar, Übungsaufgaben, Wo steht was
├── Verstehen/        Konzepte — warum das Netz so gebaut ist
├── Nachschlagen/     Register — Zahlen, Namen, Tabellen, Dienst-Steckbriefe
├── Checklisten/      Nummerierte Handlungsanweisungen, druckbar
│   ├── Notfall/  Alltag/  Personal/  Turnus/
├── Prozesse/         Änderungen, Störungsbearbeitung, Dokumentationsregeln
├── Personen/         Rollen und Eskalation
├── Templates/        Vorlagen (nicht veröffentlicht)
├── attachments/      Bilder und Anhänge
└── private/          Nur lokal, nicht veröffentlicht (Dataview-Dashboard)

quartz/               Quartz-Engine (Upstream, nicht anfassen —
                      Ausnahme: styles/custom.scss)
quartz.config.yaml    Theme, Plugins, Layout, ignorePatterns

Jeder Ordner hat eine index.md als Startseite. Ordnerseiten werden immer mit vollem Pfad verlinkt ([[Verstehen/index|Verstehen]]), weil [[index]] bei mehreren Ordnerseiten nicht eindeutig wäre.

Konventionen

• Frontmatter nach Vorlage ausfüllen: type, bereich, status, description. updated heißt „Datei angefasst", geprueft heißt „Inhalt gegen die Realität gehalten" — nur bewusst setzen.
• Keine Umlaute in Frontmatter-Schlüsseln. Der Bases-Ausdrucksparser akzeptiert nur ASCII in Bezeichnern, sonst lassen sich Felder nicht in Registern verwenden.
• Checklisten-Schritte sind nummerierte Listen, keine - [ ]-Checkboxen. Checkboxen sammelt das Tasks-Plugin vault-weit ein und sind echten offenen Aufgaben vorbehalten.
• Register, die auch online sichtbar sein sollen, sind Bases-Dateien (.base). Dataview rendert nur in Obsidian — auf der Website bliebe die Query ein Codeblock. Deshalb liegt das Dataview-Dashboard unter private/.
• Technische Ist-Daten gehören nach NetBox, nicht in den Vault. Auszüge hier tragen ein Stand:-Datum und den Verweis dorthin.
• Zugangsdaten ausschließlich in Vaultwarden.
• Druckbare Checklisten: Die Print-Regeln stehen in quartz/styles/custom.scss (der vom Upstream vorgesehene Hook). Achtung: Ein Engine-Update kann die Datei überschreiben.