PKR-Lab

Wiki-Sync (wiki-docs-sync)

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/wiki-sync.md

Wiki-Sync (wiki-docs-sync)

Der Wiki-Sync spiegelt dieses Docs-Repo (pkr-lab-docs) nach Wiki.js im PROD-Cluster. Er läuft als CronJob alle 15 Minuten. Der Code liegt im Repo capulus-wiki-sync, das Helm-Chart in capulus-core.

Überblick

flowchart LR
  docs["pkr-lab-docs (GitHub)"] -->|"1 Aufruf: Tarball"| job["CronJob wiki-docs-sync<br/>Image ghcr.io/pkr-lab/capulus-wiki-sync"]
  job -->|"REST-API, interner Service"| wiki["Wiki.js 3 (wikijs-Namespace)"]
  sec1["SealedSecret github-api-token"] -.-> job
  sec2["SealedSecret wiki-docs-sync-wikijs-token"] -.-> job
  renovate["Renovate"] -->|"Image-Tag"| chart["Chart wiki-docs-sync (capulus-core)"]
  release["Release capulus-wiki-sync vX.Y.Z"] -->|"baut Image"| job
Frage Antwort
Quelle GitHub-Repo pkr-lab/pkr-lab-docs, Branch main, geladen als Tarball über die GitHub-API (ein API-Aufruf pro Lauf)
Ziel Wiki.js 3 im Namespace wikijs (REST-API unter /_api), Locale en, Pfad-Präfix docs
Auslöser CronJob */15 * * * * (Zeitzone Europe/Berlin), concurrencyPolicy: Forbid
Authentifizierung GitHub-Token aus dem SealedSecret github-api-token (optional, hebt das Rate-Limit), Wiki.js-API-Key aus wiki-docs-sync-wikijs-token
Zustand keiner im Cluster; GitHub ist bei jedem Lauf die einzige Quelle der Wahrheit

Was der Sync mit den Seiten macht

Idempotenz und Löschen

Rendern und Wiederholungen

Konfiguration

Alle Werte stehen in argocd/apps/prod/wiki-docs-sync/values.yaml und kommen als Umgebungsvariablen im Container an.

Wert in values.yaml Variable Standard Bedeutung
image.repository, image.tag – ghcr.io/pkr-lab/capulus-wiki-sync, vX.Y.Z Image; der Tag wird von Renovate angehoben
github.owner, repo, branch GITHUB_OWNER, GITHUB_REPO, GITHUB_BRANCH pkr-lab, pkr-lab-docs, main Quelle
github.exclude EXCLUDE siehe oben Glob-Muster (kommagetrennt)
github.tokenSecretName, tokenSecretKey GITHUB_TOKEN github-api-token, token GitHub-Token; leer = anonym
wikijs.url WIKIJS_API_URL http://wikijs.wikijs.svc.cluster.local interner Service, nicht die öffentliche URL
wikijs.locale WIKIJS_LOCALE en Locale; gehört nicht in den Pfad, Wiki.js setzt es selbst davor
wikijs.pathPrefix WIKIJS_PATH_PREFIX docs Wurzel der gespiegelten Seiten
wikijs.legacyPrefixes WIKIJS_LEGACY_PREFIXES leer Präfixe, deren Seiten einmalig gelöscht werden (siehe Umstellung)
wikijs.dryRun DRY_RUN false true = nur protokollieren, nichts ändern; vor größeren Änderungen an Quelle oder Präfix einschalten
wikijs.minPages MIN_PAGES 20 Mindestzahl an Seiten, sonst Abbruch
wikijs.tokenSecretName, tokenSecretKey WIKIJS_API_TOKEN wiki-docs-sync-wikijs-token, token Wiki.js-API-Key
– WIKIJS_SITE_ID leer Site-ID in Wiki.js 3; leer = über /_api/bootstrap ermitteln
– RENDER_BATCH 8 Render-Aufträge pro Lauf, mindestens 1

Ungültige Zahlen in MIN_PAGES oder RENDER_BATCH und fehlende Pflichtvariablen (WIKIJS_API_URL, WIKIJS_API_TOKEN) beenden den Container mit Exit-Code 2.

Der GitHub-Token braucht für das öffentliche Docs-Repo nur Lesezugriff auf öffentliche Repos. Wird das Docs-Repo privat, braucht er Leserecht auf pkr-lab-docs.

Releases und Image

capulus-wiki-sync wird mit semantic-release versioniert (zentraler Workflow, github-workflows). Jedes Release baut das Image ghcr.io/pkr-lab/capulus-wiki-sync:vX.Y.Z auf python:3.15-slim; es enthält nur das Paket wikisync/ und nutzt nur die Standardbibliothek. Renovate öffnet in capulus-core einen PR, der image.tag anhebt (Regel in renovate.json). Das Image enthält keine Zugangsdaten und kann öffentlich sein, dann braucht der Namespace kein Pull-Secret (imagePullSecrets in den Values).

Entwicklung und CI

Prüfung Befehl Inhalt
unittest python3 -m unittest discover -s . -t . Tests für Konfiguration, Quelle, Rendern, Abgleich und den REST-Client (tests/test_wikijs.py, mit gemocktem urlopen, ohne Netz)
ruff und mypy python3 -m pip install -r requirements-dev.txt && ruff check . && mypy Regeln in pyproject.toml (ruff E, F, I, UP, B; mypy --strict für wikisync/)
docker build docker build -t capulus-wiki-sync:ci . && docker run --rm capulus-wiki-sync:ci Aufruf ohne Konfiguration muss mit Exit-Code 2 enden
gitleaks – Secret-Scan der Historie

Umstellung vom alten Sync (durchgeführt am 2026-10-18)

Der alte Sync las capulus-core/docs (eine Ebene tief) und schrieb nach Github/capulus-core/docs/… samt Seite Github/capulus-core/ReadMe. Die Umstellung lief so, und derselbe Ablauf eignet sich für einen Wechsel des Präfixes:

  1. Image capulus-wiki-sync veröffentlichen, Paket öffentlich stellen.
  2. Chart mit dryRun: true mergen. Das Log des ersten Jobs zeigte neu=274 gelöscht=0 Fehler=0.
  3. dryRun: false setzen. Der erste echte Lauf legte alle 274 Seiten an, der zweite meldete unverändert=274.
  4. Einmalig wikijs.legacyPrefixes: ["Github/capulus-core"] setzen: Der nächste Lauf löschte die 145 alten Seiten, danach wurde der Wert wieder geleert.
  5. docs/ und die Komponenten-READMEs aus capulus-core entfernen.

Das Log eines Laufs liest man ohne Zugriff auf den PROD-Cluster über den ArgoCD-Hub: argocd app logs prod-wiki-docs-sync --core --kind Job --name wiki-docs-sync-<Minuten seit Epoche des Slots>. Offen bleibt in Wiki.js die Navigation: Administration → Navigation → „Site Tree“.

Die URLs der Seiten haben sich geändert. Verweise auf alte Wiki-Seiten müssen angepasst werden.

Fehlersuche

Symptom Ursache und Abhilfe
Job endet mit Quelle nicht verwendbar GitHub nicht erreichbar oder Rate-Limit; Token im Secret github-api-token prüfen
Nur N Seiten, mindestens 20 erwartet Quelle leer oder Branch falsch; nichts wurde geändert
zurückgestellt=N bleibt über mehrere Läufe hoch Mehr Änderungen als RENDER_BATCH pro Lauf; abwarten oder RENDER_BATCH erhöhen
Site-ID nicht ermittelbar, WIKIJS_SITE_ID setzen /_api/bootstrap liefert keine Site; die ID in Wiki.js nachsehen und als WIKIJS_SITE_ID setzen
HTTP 403 … error code 1010 wikijs.url zeigt auf die öffentliche Cloudflare-URL; den internen Service verwenden
API Key invalid oder API disabled im Wechsel Wiki.js läuft mit mehr als einem Pod; maxReplicas bleibt 1 (siehe 60050)
Verweise auf Überschriften im Wiki führen ins Leere Wiki.js bildet Anker anders als GitHub (z. B. bei Umlauten); der Sync lässt Anker unverändert
Mermaid-Diagramme erscheinen als Code In Wiki.js unter Administration → Rendering → Markdown „Mermaid“ aktivieren
Bilder fehlen Das Docs-Repo ist privat; Bilder werden über raw.githubusercontent.com geladen und brauchen ein öffentliches Repo