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/undargocd/apps/prod/wiki-docs-sync/· URLhttps://wiki.prod.homeserverundhttps://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 offiziellenpostgres-Image —
weniger Abhängigkeiten, kein Risiko durch zukünftige Bitnami-Breaking-Changes.
Voraussetzungen
- ArgoCD läuft und das Root-ApplicationSet ist aktiv (
argocd/bootstrap/root-applicationset.yaml) - Sealed-Secrets Controller ist installiert (
argocd/apps/tech/sealed-secrets/) nas-storage-App ist deployt (argocd/apps/tech/nas-storage/) und die
StorageClassnasexistiert:kubectl get storageclass nas- NAS ist online und der NFS-Export erreichbar (siehe
capulus-core/2-betrieb-hardware/20000-nas-storage.md) — sonst bleibt die
PostgreSQL-PVC aufPending kubesealCLI ist lokal installiertkubectlist mit dem Cluster verbunden
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:
wikijs-postgresql-*startet zuerst (PVC aufnas, kein Node-Pin mehr)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-*dauerhaftPendingbleibt: das NAS ist
offline oder dienas-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
- Browser öffnen:
https://wiki.prod.homeserver - Setup-Wizard durchlaufen:
- Site-Titel vergeben
- Admin-Account: E-Mail + Passwort festlegen
- Telemetrie-Einstellung nach Wunsch
- 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:
- Eine Group definiert globale Basis-Rechte (lesen/schreiben/verwalten)
für ihre Mitglieder. - Pro Group lassen sich zusätzlich Page Rules anlegen: pfadbasierte
Regeln (z. B. "Pfad beginnt mitvereins-intern/"), die Lesen/Schreiben/
Verwalten gezielt erlauben oder verweigern — unabhängig von den globalen
Rechten der Group. - Spezifischere Regeln überschreiben generischere; bei gleicher Spezifität
gewinnt "Verweigern" gegen "Erlauben". Ohne explizite Erlaubnis ist eine
Aktion immer verweigert (Default-Deny).
4.1 — Beispiel-Konzept: "öffentlich lesbar" + "intern voller Zugriff"
In Wiki.js (Administration → Groups → Erstellen) zwei Groups anlegen:
Group "Lesend"
- Tab Permissions: nur
read:pagesglobal aktivieren - Tab Page Rules → Erstellen:
- Pfad:
/(oder gezieltpublic/), Match:Start (Starts with) - Berechtigung:
Lesen→ Erlauben - Optional: Pfad
intern/, Match:Start, BerechtigungLesen→ Verweigern
(überschreibt die generischere/-Regel für diesen Unterpfad)
- Pfad:
Group "Redaktion"
- Tab Permissions:
read:pages,write:pages,manage:pages,read:comments,write:commentsglobal aktivieren - 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:
- 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 - Wiki.js auf 0 Replicas skalieren (
kubectl -n wikijs scale deploy/wikijs --replicas=0). - In der Chart-Vorlage:
values.yaml:postgresql.image.tag: "16-alpine"→"18-alpine"templates/postgres-deployment.yaml:PGDATAvon
/var/lib/postgresql/data/pgdata_fixedauf
/var/lib/postgresql/data/pgdata_fixed_pg18ändern.runAsUser/
runAsGroup: 1000/10bleiben unverändert — die Squash-Identität
betrifft nur den Verzeichnis-Owner, nicht die Postgres-Version.- Committen/pushen, ArgoCD syncen lassen.
- Dump zurückspielen (
kubectl cp+pg_restore -U wikijs -d wiki,
analog zu Nextcloud). - Wiki.js wieder hochskalieren, Login + ein paar Seiten prüfen.
- Rollback: Schritt 3 revertieren, alter
pgdata_fixed-Ordner liegt
unangetastet auf derselben PVC. - 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.