PKR-Lab

30030 - Wiki.js

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/30030-wikijs.md

Wiki.js

Cluster: PROD · Ordner argocd/apps/prod/wikijs/ und argocd/apps/prod/wiki-docs-sync/ · URL https://wiki.prod.homeserver und https://wiki-prod.pke-lab.de. kubectl-Befehle in diesem Doc gelten für den PROD-Cluster (Zugriff je Cluster).

Wiki.js ist ein Open-Source-Wiki/Knowledge-Base-System mit Markdown-Editor,
eingebauten Benutzergruppen und pfadbasierten Zugriffsregeln (Page Rules).
Die Deployment-Konfiguration liegt unter argocd/apps/prod/wikijs/. Die Inhalte kommen aus dem Docs-Repo pkr-lab-docs und werden vom CronJob wiki-docs-sync gespiegelt, siehe wiki-sync; Änderungen am Inhalt macht man im Docs-Repo, nicht im Wiki.


Übersicht

Komponente Technologie Namespace
Wiki.js App Node.js (ghcr.io/requarks/wiki) wikijs
Datenbank PostgreSQL 16 (eigenes Deployment) wikijs
Ingress Traefik wikijs
Secrets SealedSecrets wikijs
Persistenz StorageClass nas (UGREEN NAS, NFS) —

Wiki.js speichert sämtliche Inhalte — Seiten, Versionshistorie und
hochgeladene Assets (Bilder, PDFs, etc.) — direkt in PostgreSQL. Der
Wiki.js-Pod selbst ist zustandslos und braucht kein eigenes PVC; nur
PostgreSQL benötigt Persistenz. PostgreSQL läuft mit storageClassName: nas
(siehe capulus-core/2-betrieb-hardware/20000-nas-storage.md) — keine NodeAffinity
mehr nötig, damit liegen alle Wiki-Daten auf dem NAS statt auf der
Homeserver-System-SSD.

Warum kein Bitnami-PostgreSQL-Subchart wie bei Zammad?
Bitnami hat im August 2025 sein kostenloses Chart-Katalog-Angebot stark
eingeschränkt (Legacy-Images ohne weitere Updates, neue Versionen nur noch
per Subscription). Für eine einzelne, kleine Wiki-Datenbank reicht ein
schlankes eigenes Deployment mit dem offiziellen postgres-Image —
weniger Abhängigkeiten, kein Risiko durch zukünftige Bitnami-Breaking-Changes.


Voraussetzungen


Schritt 1 — Secret versiegeln

Vor dem ersten Deployment muss das Datenbank-Passwort versiegelt werden.
Im Gegensatz zu Zammad reicht hier ein Wert für einen Secret-Key —
sowohl PostgreSQL (POSTGRES_PASSWORD) als auch Wiki.js (DB_PASS) lesen
denselben Key db-password aus demselben Secret.

# Passwort generieren
DB_PASS=$(openssl rand -base64 32 | tr -d '=+/' | head -c 32)
echo "DB_PASS: $DB_PASS"   # sicher speichern (z. B. Passwort-Manager)

# Versiegeln
echo -n "$DB_PASS" | kubeseal --raw \
  --namespace wikijs \
  --name wikijs-secrets \
  --controller-namespace sealed-secrets \
  --controller-name sealed-secrets-controller

Die Ausgabe in argocd/apps/prod/wikijs/values.yaml eintragen:

secrets:
  enabled: true
  name: wikijs-secrets
  encryptedDbPassword: "<Ausgabe von kubeseal>"

Wichtig: Niemals Klartext-Passwörter committen — nur den versiegelten Ciphertext-Blob.


Schritt 2 — Deployment via ArgoCD

Nach dem Commit der Änderungen erkennt das Root-ApplicationSet den neuen Ordner
argocd/apps/prod/wikijs/ automatisch und erstellt die ArgoCD-Application.

ArgoCD → Home → wikijs
Status: Syncing → Healthy

Sync-Fortschritt beobachten:

kubectl get pods -n wikijs -w

Erwartete Reihenfolge:

  1. wikijs-postgresql-* startet zuerst (PVC auf nas, kein Node-Pin mehr)
  2. wikijs-* (App-Pod) — verbindet sich mit PostgreSQL und führt beim ersten
    Start automatisch die DB-Migrationen durch (kann 1–2 Minuten dauern)

Falls wikijs-postgresql-* dauerhaft Pending bleibt: das NAS ist
offline oder die nas-StorageClass fehlt — siehe
capulus-core/2-betrieb-hardware/20000-nas-storage.md → Fehlerbehebung.

DNS: Wiki.js läuft im PROD-Cluster, deshalb steht wiki.prod.homeserver in
dnsmasq_prod_vm_hosts (capulus-ansible/group_vars/all.yml) und zeigt auf die PROD-VM (.99); die
allgemeine Wildcard address=/homeserver/<server-ip> würde auf TECH zeigen (siehe
capulus-core/c-netzwerk-dns/c0040-domain-tiers.md).


Schritt 3 — Ersten Admin-Account anlegen

  1. Browser öffnen: https://wiki.prod.homeserver
  2. Setup-Wizard durchlaufen:
    • Site-Titel vergeben
    • Admin-Account: E-Mail + Passwort festlegen
    • Telemetrie-Einstellung nach Wunsch
  3. Login mit den im Wizard erstellten Zugangsdaten

Schritt 4 — Berechtigungskonzept: Bereiche mit unterschiedlichen Rechten

Kurze Antwort auf die Ausgangsfrage: Eine zweite App ist dafür nicht
nötig. Wiki.js bringt mit Groups + Page Rules genau dieses Feature
bereits eingebaut mit:

4.1 — Beispiel-Konzept: "öffentlich lesbar" + "intern voller Zugriff"

In Wiki.js (Administration → Groups → Erstellen) zwei Groups anlegen:

Group "Lesend"

  1. Tab Permissions: nur read:pages global aktivieren
  2. Tab Page Rules → Erstellen:
    • Pfad: / (oder gezielt public/), Match: Start (Starts with)
    • Berechtigung: Lesen → Erlauben
    • Optional: Pfad intern/, Match: Start, Berechtigung Lesen → Verweigern
      (überschreibt die generischere /-Regel für diesen Unterpfad)

Group "Redaktion"

  1. Tab Permissions: read:pages, write:pages, manage:pages, read:comments, write:comments global aktivieren
  2. Keine einschränkenden Page Rules nötig — volle Rechte überall

So entsteht z. B. ein öffentlich lesbarer Bereich (Checklisten, SOPs für
alle) und ein interner Bereich, den nur die Redaktion sehen und bearbeiten
kann — ein einziges Wiki, klar getrennte Sichtbarkeiten.

Mehr Details zu Match-Typen (Starts With / Ends With / Regex / Exact) und
Regel-Priorität: docs.requarks.io/groups.


Datenbank-Major-Upgrade (Postgres 16 → 18)

Gleiches Prinzip wie bei Nextcloud:
ein reiner Tag-Bump auf postgres:18-alpine lässt den Pod crashloopen,
weil das bestehende Datenverzeichnis noch im Postgres-16-Format ist.
Hier zusätzlich zu beachten: PGDATA zeigt schon auf pgdata_fixed (nicht
pgdata) — Folge des Squash-Identity-Fixes weiter oben in dieser Datei
(NFS-Export squasht auf UID/GID 1000:10). Für das Upgrade denselben
Trick anwenden, nur mit einem weiteren neuen Unterordner:

  1. Dump (zusätzlich zum nächtlichen restic-Backup, siehe
    capulus-core/2-betrieb-hardware/20010-nas-backup.md):
    kubectl -n wikijs exec deploy/wikijs-postgresql -- \
      pg_dump -U wikijs -Fc wiki > wikijs-pg16-$(date +%F).dump
    
  2. Wiki.js auf 0 Replicas skalieren (kubectl -n wikijs scale deploy/wikijs --replicas=0).
  3. In der Chart-Vorlage:
    • values.yaml: postgresql.image.tag: "16-alpine" → "18-alpine"
    • templates/postgres-deployment.yaml: PGDATA von
      /var/lib/postgresql/data/pgdata_fixed auf
      /var/lib/postgresql/data/pgdata_fixed_pg18 ändern. runAsUser/
      runAsGroup: 1000/10 bleiben unverändert — die Squash-Identität
      betrifft nur den Verzeichnis-Owner, nicht die Postgres-Version.
    • Committen/pushen, ArgoCD syncen lassen.
  4. Dump zurückspielen (kubectl cp + pg_restore -U wikijs -d wiki,
    analog zu Nextcloud).
  5. Wiki.js wieder hochskalieren, Login + ein paar Seiten prüfen.
  6. Rollback: Schritt 3 revertieren, alter pgdata_fixed-Ordner liegt
    unangetastet auf derselben PVC.
  7. Nach störungsfreier Testphase alten pgdata_fixed-Ordner aufräumen.

Troubleshooting

Wiki.js-Pod startet, bleibt aber Not Ready

kubectl logs -n wikijs -l app.kubernetes.io/name=wikijs

Meist liegt es an einer noch laufenden DB-Migration (erster Start) oder
einer falschen DB_HOST/DB_PASS-Kombination.

PostgreSQL-Pod startet nicht / CrashLoopBackOff

kubectl logs -n wikijs -l app.kubernetes.io/name=wikijs-postgresql
kubectl describe pod -n wikijs -l app.kubernetes.io/name=wikijs-postgresql

SealedSecret wird nicht entschlüsselt

kubectl describe sealedsecret -n wikijs wikijs-secrets
kubectl logs -n sealed-secrets -l app.kubernetes.io/name=sealed-secrets

PostgreSQL-PVC bleibt Pending

PostgreSQL läuft auf der nas-StorageClass (NFS, UGREEN NAS):

kubectl describe pvc -n wikijs wikijs-postgresql-data
kubectl -n nas-storage get pods

Details: capulus-core/2-betrieb-hardware/20000-nas-storage.md → Fehlerbehebung.


Ressourcenverbrauch (Richtwerte Home Lab)

Komponente CPU Request RAM Request RAM Limit Storage
Wiki.js App 100m 256Mi 512Mi —
PostgreSQL 50m 256Mi 512Mi 20Gi (nas)
Gesamt ~150m ~512Mi ~1Gi 20Gi auf dem NAS

Die 20Gi für PostgreSQL sind ein Startwert (Seiten + Assets liegen beide in
der DB) — bei Bedarf in argocd/apps/prod/wikijs/values.yaml unter
postgresql.persistence.size erhöhen.


Autoskalierung (HPA)

Die Wiki.js-App-Komponente skaliert per HPA auf 1–3 Replicas (CPU 75% /
RAM 80%) — da Seiten und Assets vollständig in PostgreSQL liegen (kein
PVC am App-Pod), ist das ohne weitere Vorkehrungen (kein Affinity-Trick
nötig) sicher. PostgreSQL selbst bleibt unangetastet (Single-Writer,
kein HPA). Details für alle Apps: ../b-kubernetes-gitops/b0040-hpa-autoscaling.md.