Wiki.js mit PostgreSQL auf Unraid installieren

Warum Postgres? Wiki.js läuft mit mehreren Datenbanken, aber Postgres ist die empfohlene und zukunftssichere Wahl. Für Wiki.js 3.x ist Postgres sogar Pflicht.

Zielbild

• Ein PostgreSQL-Container für die Daten
• Ein Wiki.js-Container (2.x, stabil)
• Beide auf einer gemeinsamen Docker-Bridge (Kommunikation per Containernamen)
• Persistente Volumes in /mnt/user/appdata/...
• Optional: Reverse Proxy (Nginx Proxy Manager / SWAG) für HTTPS

Voraussetzungen

• Unraid 6.12+ mit Community Apps
• Terminalzugriff (Web-Terminal auf Unraid)
• Eine freie interne Bridge-IP / Port 3000 (oder anders gemappt)

Schritt 1: Docker-Netzwerk anlegen (saubere Namensauflösung)

Öffne auf Unraid das Terminal:

docker network create wikinet

Das sorgt dafür, dass sich die Container später über ihre Namen erreichen (z. B. DB_HOST=postgres-wikijs). (Offizielle Praxisempfehlung in den Installguides.)

Schritt 2: PostgreSQL-Container anlegen

Community Apps → Add Container (benutzerdefiniert)

• Name: postgres-wikijs
• Repository: postgres:16-alpine
• Network Type: wikinet
• Port: keine Host-Portfreigabe nötig, die App spricht intern über das Docker-Netz (optional 5432:5432, wenn du externen Zugriff willst)
• Path/Volume:
  • Container Path: /var/lib/postgresql/data → Host Path: /mnt/user/appdata/postgres-wikijs
• Environment Variables:
  • POSTGRES_DB=wikijs
  • POSTGRES_USER=wikijs
  • POSTGRES_PASSWORD=<starkesPasswort>
  • (Optional) POSTGRES_INITDB_ARGS=--encoding=UTF8 --lc-collate=C --lc-ctype=C

Warum so? Genau diese Variablen erwartet das offizielle Postgres-Image.

Speichern & Starten.

Schritt 3: Wiki.js-Container anlegen (stabile 2.x)

Nutze bewusst Wiki.js 2.x als “stable” und pinne den Tag (:2 oder :2.5), nicht latest. 3.x ist Stand heute noch alpha und nur für Tests gedacht.

Community Apps → Add Container (benutzerdefiniert)

• Name: wikijs
• Repository (eine der beiden Varianten):
  • Docker Hub: requarks/wiki:2.5 (oder :2)
  • Oder GitHub Packages: ghcr.io/requarks/wiki:2.5 (gleiches Image, andere Registry)
• Network Type: wikinet
• Port Mapping: Host 3000 → Container 3000 (oder Host 8080, wenn 3000 belegt ist)
• Path/Volume:
  • Container Path: /wiki → Host Path: /mnt/user/appdata/wikijs
• Environment Variables (DB-Bindung):
  • DB_TYPE=postgres
  • DB_HOST=postgres-wikijs
  • DB_PORT=5432
  • DB_USER=wikijs
  • DB_PASS=<gleiches starkesPasswort>
  • DB_NAME=wikijs
  • (Optional) TZ=Europe/Berlin

Die DB-Variablen sind die offiziell dokumentierten für Wiki.js-Container.

Speichern & Starten.

Schritt 4: Ersteinrichtung im Browser

Rufe http://<UNRAID-IP>:3000 auf. Der Setup-Wizard von Wiki.js führt dich durch Admin-Account, Titel, Sprache etc. (Bei 2.x erfolgt der Admin-Setup im UI; bei 3.x gäbe es ENV-Shortcuts, aber 3.x ist noch nicht für Produktion.)

Schritt 5 (optional): Reverse Proxy & HTTPS

Für eine saubere öffentliche URL nutze deinen bestehenden Reverse Proxy (Nginx Proxy Manager / SWAG):

• Proxy Host: wikijs.deine-domain.tld
• Forward IP: <UNRAID-IP>
• Forward Port: 3000
• SSL: Let’s Encrypt aktivieren (HTTP-Validierung), HSTS optional.

Wiki.js kann auch eigene SSL-Einstellungen per Config/ENV, in der Praxis ist ein externer Reverse Proxy auf Unraid jedoch einfacher. (Die Docs zeigen beide Wege.)

Schritt 6: Updates & Wartung

• Image aktualisieren: In Unraid bei wikijs → Update ausführen (oder docker pull & Container neu erstellen).
• Bleib auf dem Haupt-Tag :2 oder :2.5, damit keine Major-Brüche reinrutschen. Die offiziellen Upgrade-Notes empfehlen das explizit.

Backups (kurz & konkret)

1. Postgres-Dump (empfohlen): docker exec -t postgres-wikijs pg_dump -U wikijs -d wikijs > /mnt/user/backups/wikijs/wikijs_$(date +%F).sql
2. Appdata sichern:
   • /mnt/user/appdata/postgres-wikijs (DB-Datenfiles)
   • /mnt/user/appdata/wikijs (Config/Logs/Cache)

Die offizielle Doku beschreibt Transfer/Restore-Pfade zwischen Servern; für Unraid nutzt du die gleichen Prinzipien (Dump einspielen, Container mit gleichen ENV starten).

Von SQLite auf PostgreSQL umziehen (falls du schon mit SQLite gestartet bist)

Es gibt keine offizielle 1-Klick-DB-Konvertierung von SQLite auf Postgres. Die gängige, saubere Methode ist:

1. Neue Postgres-Instanz wie oben bereitstellen.
2. Neues Wiki.js gegen Postgres starten.
3. Inhalt aus alter Instanz exportieren (Seiten/Assets) und im neuen Wiki importieren.
   • Nutzer/Rollen/Einstellungen setzt du neu.
   • Alternativ ist eine manuelle DB-Konvertierung via Dumps möglich, aber fehleranfällig und nicht offiziell unterstützt.

Bonus: Wer langfristig auf Wiki.js 3.x will, muss vorher auf Postgres sein.

Troubleshooting (die typischen Stolpersteine)

• Database connection error
  • Prüfe DB_HOST exakt auf Containernamen (postgres-wikijs) und dass beide Container im gleichen Netzwerk (wikinet) laufen.
• Zeitüberschreitung beim Start
  • Postgres braucht 5–10 Sekunden; Wiki.js notfalls einmal neu starten.
• Port schon belegt
  • Anderen Host-Port wählen, z. B. 8080:3000.
• Leistung
  • Für mittelgroße Wikis: 2 vCPU/1–2 GB RAM reichen meist. Offizielle Deploy-Guides und Cloud-One-Click-App nennen ähnliche Größenordnungen.

(Optional) Docker-Compose für Fortgeschrittene

Falls du das Docker Compose Plugin nutzt, hier ein minimalistisches, solides Compose-Beispiel:

services:
  db:
    image: postgres:16-alpine
    container_name: postgres-wikijs
    networks: [wikinet]
    environment:
      POSTGRES_DB: wikijs
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: ${PG_PASSWORD}
    volumes:
      - /mnt/user/appdata/postgres-wikijs:/var/lib/postgresql/data
    restart: unless-stopped

  wiki:
    image: requarks/wiki:2.5
    container_name: wikijs
    depends_on: [db]
    networks: [wikinet]
    environment:
      DB_TYPE: postgres
      DB_HOST: postgres-wikijs
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: ${PG_PASSWORD}
      DB_NAME: wikijs
      TZ: Europe/Berlin
    ports:
      - "3000:3000"
    volumes:
      - /mnt/user/appdata/wikijs:/wiki
    restart: unless-stopped

networks:
  wikinet:
    external: true

Environment-Variablen & Tag-Empfehlungen sind konform zur offiziellen Doku.

Kurzfazit

• Postgres lohnt sich für Stabilität, Suche und Zukunftssicherheit.
• Auf Unraid ist die DB-Kopplung mit DB_*-Variablen in 5 Minuten gesetzt.
• Updates gelassen angehen: Tag pinnen (:2.5), regelmäßig Backups ziehen.