Thomas/Homelab--Bratonein-Kontrollzentrum--Tutorial

Files

Thomas Dannenberg 006cfb0bcf Kapitel 14/Free Rohtext.md hinzugefügt

2025-10-16 17:52:42 +00:00

18 KiB

Raw Blame History

Kapitel 14 – Wiki (Self-Hosted mit Wiki.js)

Einleitung

Das eigene Wiki-System ist ein zentraler Bestandteil des UCC und dient als interne Wissensbasis für Dokumentationen, Abläufe und Notizen.
Mit Wiki.js baust du eine moderne, leicht bedienbare Plattform auf, die du vollständig selbst kontrollierst – ohne Cloud-Abhängigkeiten oder externe Accounts.
Gerade für Content Creator, Streamer oder kleine Teams ist das ideal, um Anleitungen, Skripte, Ideen oder Projektbeschreibungen zentral zu verwalten.

👉 Screenshot geeignet: Übersicht UCC-Struktur mit hervorgehobener Position von Wiki.js zwischen Gitea (Code) und Nextcloud (Dateien)

Wiki.js kombiniert das Beste aus Markdown, Rollenverwaltung und Suchfunktion zu einer klaren, schnellen Weboberfläche.
Alle Inhalte werden strukturiert in einer PostgreSQL-Datenbank gespeichert, wodurch Änderungen versioniert und nachvollziehbar bleiben.

Note

Wiki.js ist keine einfache Notiz-App, sondern ein vollwertiges, selbst gehostetes Wissenssystem.
Es kann Markdown, visuelle Editoren, Benutzerrechte, Authentifizierung über externe Systeme und mehr.

Im Gegensatz zu klassischen Wiki-Lösungen wie DokuWiki oder MediaWiki ist Wiki.js modern, performant und Docker-basiert.
Das bedeutet: minimale Wartung, saubere Updates und klar trennbare Datenbereiche.

Ziel dieses Kapitels ist es, eine vollständig funktionsfähige Wiki.js-Instanz im Debian-12-LXC zu installieren.
Am Ende steht ein System, das du über HTTPS unter deiner eigenen Subdomain aufrufst – mit Admin-Zugang, aktivem Rechte-Management und stabiler Datenbasis.

👉 Screenshot geeignet: Zielzustand – Browser mit Wiki.js-Startseite unter https://wiki.deinedomain.tld

Voraussetzungen & Ressourcen

Bevor du mit der Einrichtung des Wiki-LXC beginnst, überprüfe die technischen Voraussetzungen.
Wiki.js läuft ressourcenschonend, benötigt aber eine stabile Basis, um Datenbank und Weboberfläche zuverlässig zu betreiben.

Container-Ressourcen

CPU: 1 vCPU
Für normale Nutzung vollkommen ausreichend. Bei vielen gleichzeitigen Zugriffen kann später erweitert werden.
RAM: 2 GB
Diese Größe stellt sicher, dass sowohl die PostgreSQL-Datenbank als auch der Node.js-Dienst stabil arbeiten.
Weniger Arbeitsspeicher führt erfahrungsgemäß zu Abbrüchen beim Start oder bei Updates.
Speicherplatz: 20 GB
Genug für System, Datenbank, Uploads und Logs.
Wenn du viele Medien (z. B. Bilder) speicherst, plane von Beginn an mehr Speicher ein.
Betriebssystem: Debian 12 (Bookworm)
Alle Befehle in diesem Kapitel beziehen sich auf Debian 12.
Andere Distributionen oder Versionen können abweichende Paketnamen oder Pfade haben.
Netzwerk: statische IP-Adresse oder DHCP-Reservierung
Der Container muss dauerhaft unter derselben IP erreichbar sein,
da die Proxy-Einbindung und DNS-Zuordnung fest auf diese Adresse verweisen.

Tip

Weise die IP-Adresse direkt beim Erstellen des Containers in Proxmox zu.
Eine spätere Änderung führt zu Verbindungsfehlern in NPM und SSL-Neuausstellungen.

Technische Voraussetzungen

Proxmox VE ist installiert und aktiv.
Der Container wird direkt über die Proxmox-Oberfläche erstellt und verwaltet.
Nginx Proxy Manager (NPM) ist eingerichtet.
Er wird benötigt, um die Wiki.js-Weboberfläche über HTTPS bereitzustellen.
DNS- oder DynDNS-Eintrag für wiki.deinedomain.tld ist angelegt.
Internetverbindung innerhalb des Containers ist aktiv.
Wiki.js und PostgreSQL werden per Docker-Image aus dem Internet geladen.
SSH-Zugriff auf den Container ist möglich (z. B. ssh root@10.0.0.14).

Important

Stelle sicher, dass der Container auf einem Host mit stabiler Netzwerkverbindung läuft
und nicht auf demselben Volume wie stark ausgelastete Produktionsdienste liegt.

👉 Screenshot geeignet: Ressourcenübersicht beim Erstellen des Wiki-LXC (vCPU, RAM, Storage)

Schritt-für-Schritt-Anleitung

In diesem Abschnitt richtest du den Wiki-LXC vollständig ein.
Alle Befehle sind direkt übernehmbar. Am Ende ist Wiki.js per HTTPS unter deiner Subdomain erreichbar.

Schritt 1 – System aktualisieren

Starte den Container und öffne die Konsole (Proxmox oder SSH). Führe ein Update durch und starte neu.

apt update && apt upgrade -y
reboot

Nach dem Neustart erneut einloggen.

Note

Ein frischer LXC hat oft veraltete Paketquellen. Updates verhindern spätere Docker-Fehler.

👉 Screenshot geeignet: Proxmox-Konsole mit erfolgreichem apt upgrade

Schritt 2 – Grundpakete installieren

Installiere Werkzeuge für HTTPS-Repos und GPG-Schlüssel.

apt install -y ca-certificates curl gnupg lsb-release

Tip

Diese Pakete brauchst du gleich für das offizielle Docker-Repository.

Schritt 3 – Docker und Compose (Plugin) installieren

Binde das Docker-Repo ein, installiere Docker + Compose-Plugin und aktiviere den Dienst.

mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg

ARCH=$(dpkg --print-architecture)
CODENAME=$(lsb_release -cs)
echo "deb [arch=${ARCH} signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian ${CODENAME} stable" \
  | tee /etc/apt/sources.list.d/docker.list > /dev/null

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
systemctl enable --now docker

Prüfe den Status:

systemctl status docker

Es muss active (running) angezeigt werden.

Note

Compose nutzt hier das Plugin → Befehle starten mit docker compose … (mit Leerzeichen).

👉 Screenshot geeignet: Terminal mit systemctl status docker (active running)

Schritt 4 – Projektordner vorbereiten

Lege den Arbeitsordner an. Dort liegen Compose-Datei, .env und Persistenz.

mkdir -p /srv/wiki
cd /srv/wiki

Tip

Bewahre pro Dienst einen eigenen Ordner unter /srv/<dienst> auf. Das hält Backups und Updates übersichtlich.

Schritt 5 – Umgebungsdatei `.env` anlegen

Zugangsdaten und wiederverwendbare Einstellungen zentral halten.

nano .env

Inhalt einfügen, ersetzen, speichern (STRG+O, Enter) und schließen (STRG+X):

TZ=Europe/Berlin
POSTGRES_DB=wikidb
POSTGRES_USER=wikijs
POSTGRES_PASSWORD=<STARKES-PASSWORT>

WIKI_DB_HOST=postgres
WIKI_DB_PORT=5432
WIKI_DB_USER=${POSTGRES_USER}
WIKI_DB_PASS=${POSTGRES_PASSWORD}
WIKI_DB_NAME=${POSTGRES_DB}
WIKI_PORT=3000

Important

Notiere dir das Datenbank-Passwort sicher. Ohne das Passwort startet Wiki.js nicht.

👉 Screenshot geeignet: geöffnete .env mit ausgefüllten Variablen (Passwort unkenntlich)

Schritt 6 – `docker-compose.yaml` erstellen

Definiert PostgreSQL (Persistenz + Healthcheck) und Wiki.js (Start erst, wenn DB gesund ist).

nano docker-compose.yaml

Inhalt einfügen → speichern → schließen:

version: "3.9"
services:
  postgres:
    image: postgres:15
    container_name: wiki-postgres
    restart: unless-stopped
    env_file: .env
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      TZ: ${TZ}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 10

  wikijs:
    image: requarks/wiki:2
    container_name: wikijs
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
    env_file: .env
    environment:
      DB_TYPE: postgres
      DB_HOST: ${WIKI_DB_HOST}
      DB_PORT: ${WIKI_DB_PORT}
      DB_USER: ${WIKI_DB_USER}
      DB_PASS: ${WIKI_DB_PASS}
      DB_NAME: ${WIKI_DB_NAME}
      TZ: ${TZ}
    ports:
      - "3000:${WIKI_PORT}"
    volumes:
      - ./data/wikijs:/var/wiki

Tip

./data/postgres und ./data/wikijs enthalten alle wichtigen Daten.
Diese Ordner gehören ins Backup.

👉 Screenshot geeignet: geöffnete docker-compose.yaml mit vollständigem Inhalt

Schritt 7 – Dienste starten und prüfen

Starte die Container im Hintergrund und prüfe den Status.

docker compose up -d
docker compose ps

Logs ansehen, wenn etwas hängt:

docker logs -f wikijs
# optional parallel:
docker logs -f wiki-postgres

Die Weboberfläche ist nun intern erreichbar unter:

http://<IP-des-Containers>:3000

👉 Screenshot geeignet: Browser mit Wiki.js-Setupseite unter http://<IP>:3000

Schritt 8 – Erstkonfiguration im Browser

Rufe http://<IP-des-Containers>:3000 auf und führe die Setup-Schritte aus:

Datenbankverbindung ist bereits durch Umgebungsvariablen gesetzt (PostgreSQL).
Admin-Benutzer anlegen (Benutzername, E-Mail, starkes Passwort).
Sprache auf Deutsch, Zeitzone auf Europe/Berlin stellen.
Registrierung auf Nur Einladung oder Admin Approval setzen.

Important

Öffentliche Registrierung abschalten. Sonst kann sich jeder Account anlegen.

👉 Screenshot geeignet: Setup-Assistent mit ausgefülltem Admin-Formular

Schritt 9 – Einbindung in Nginx Proxy Manager (NPM)

Nachdem Wiki.js intern getestet wurde und über http://<IP>:3000 erreichbar ist, erfolgt nun die Integration in den Nginx Proxy Manager.
Dadurch wird das Wiki über HTTPS bereitgestellt und erhält eine feste, leicht merkbare Subdomain.

Important

Führe diesen Schritt erst aus, wenn du die Wiki.js-Oberfläche bereits über die interne IP-Adresse aufrufen kannst.
So stellst du sicher, dass eventuelle Fehler eindeutig auf den Proxy und nicht auf den Container zurückzuführen sind.

Proxy-Host für Wiki.js anlegen

Öffne das Dashboard des Nginx Proxy Manager.
Klicke auf Add Proxy Host.
Trage folgende Werte ein:

Feld	Wert
Domain Names	`wiki.deinedomain.tld`
Scheme	`http`
Forward Hostname / IP	IP-Adresse des Wiki-LXC
Forward Port	`3000`
Block Common Exploits	aktivieren
Websockets Support	aktivieren

Wechsle anschließend in den Reiter SSL:

Request a new SSL Certificate → aktivieren
Force SSL → aktivieren
HTTP/2 Support → aktivieren
HSTS Enabled → aktivieren

Speichere die Konfiguration mit Save.

👉 Screenshot geeignet: NPM-Maske mit eingetragenem Proxy-Host wiki.deinedomain.tld

Note

Nach dem Speichern wird automatisch ein gültiges Let’s-Encrypt-Zertifikat erstellt.
Damit ist die Verbindung zu deiner Wiki.js-Instanz verschlüsselt und über HTTPS erreichbar.

Verbindung prüfen

Öffne im Browser:

https://wiki.deinedomain.tld

Wenn die Login-Seite von Wiki.js angezeigt wird, funktioniert die Weiterleitung korrekt.
Logge dich mit deinem Administrator-Account ein und überprüfe, ob alle Seiten erreichbar sind.

👉 Screenshot geeignet: Browserfenster mit Wiki.js-Login unter https://wiki.deinedomain.tld

Tip

Wenn die Seite nicht lädt oder eine Fehlermeldung erscheint, prüfe im NPM-Dashboard,
ob der Forward-Port korrekt auf 3000 gesetzt ist und das SSL-Zertifikat gültig ist.

Schritt 10 – Basisabsicherung in Wiki.js

Öffne dein Wiki unter https://wiki.deinedomain.tld als Admin.

Registrierung: auf Nur Einladung oder Admin Approval stellen.
Standardrolle für neue Nutzer: Leser.
E-Mail-Vorlagen optional anpassen (Einladungen).
Backups einplanen: sichere /srv/wiki/data regelmäßig (DB + Wiki-Daten).

Tip

Lege direkt eine Startseite an (Projektübersicht, Glossar, Inhaltsverzeichnis). Das schafft Struktur für zukünftige Seiten.

1. Web-Zugriff prüfen

Rufe im Browser auf:

https://wiki.deinedomain.tld

Die Login-/Startseite muss ohne Warnung (Schloss-Symbol) laden.

Mit dem zuvor angelegten Admin anmelden.
Navigiere zu Administration → Benutzer und bestätige, dass dein Admin gelistet ist.

3. Seite anlegen

Erstellen → Seite auswählen
Titel: Start
Inhalt: kurze Projektübersicht speichern
Seite öffnen und Darstellung prüfen

4. Rechte prüfen

Administration → Sicherheit → Rollen

Standardrolle für neue Nutzer: Leser
Registrierung: Nur Einladung oder Admin Approval aktiv

5. Direktaufruf testen

Öffne deine Startseite erneut direkt per URL im Wiki und per Reload (F5).
Lade zusätzlich die Rohansicht/Markdown-Ansicht und verifiziere korrekte Darstellung.

👉 Screenshot geeignet: Browser mit https://wiki.deinedomain.tld (Schloss-Symbol sichtbar) und geöffneter Startseite

Tip

Wenn etwas nicht lädt: NPM-Eintrag (Host, Port 3000, SSL-Status) prüfen und die Container-Logs ansehen:
docker logs -f wikijs
docker logs -f wiki-postgres

Aufruf prüfen
Öffne im Browser:
```
https://wiki.deinedomain.tld
```
Die Seite muss ohne Warnung (Schloss-Symbol) laden.
Login testen
Mit dem Admin-Konto anmelden.
Menü öffnen → Administration → Benutzer → dein Admin muss gelistet sein.
Startseite anlegen
Erstellen → Seite → Titel: Start → kurzen Text speichern.
Diese Seite über Navigation → Menü bearbeiten in die Hauptnavigation aufnehmen.

👉 Screenshot geeignet: Browser mit https://wiki.deinedomain.tld (Schloss sichtbar) und geöffneter Startseite

Troubleshooting & Tipps

Auch wenn Wiki.js stabil läuft, kann es während der Einrichtung oder im späteren Betrieb zu kleineren Problemen kommen.
Die folgenden Hinweise zeigen dir die häufigsten Ursachen und die passenden Lösungen, damit du Fehler schnell findest und behebst.

Wiki.js-Weboberfläche nicht erreichbar

Wenn https://wiki.deinedomain.tld nicht geladen wird oder eine Fehlermeldung wie Verbindung fehlgeschlagen erscheint:

Prüfe, ob die Container laufen:
```
docker ps
```
Wenn wikijs oder wiki-postgres fehlen, starte sie neu:
```
docker compose up -d
```
Wenn Wiki.js nur über die IP erreichbar ist (http://10.0.0.14:3000), stimmt meist der Proxy-Eintrag nicht.
Öffne den Nginx Proxy Manager und kontrolliere:
- Forward Hostname / IP → Adresse des Wiki-LXC
- Forward Port → 3000
- Websockets Support aktiviert
- SSL-Zertifikat gültig

Tip

Nach dem Anlegen eines neuen Zertifikats kann es bis zu einer Minute dauern, bis NPM es aktiv verwendet.

👉 Screenshot geeignet: NPM-Dashboard mit aktivem Proxy-Host wiki.deinedomain.tld

Setup-Seite lädt nicht oder bleibt leer

Wenn die Einrichtung nicht startet oder nur eine weiße Seite angezeigt wird, ist Wiki.js meist noch mit der Datenbankinitialisierung beschäftigt.
Warte etwa 30 Sekunden und lade die Seite neu.
Falls weiterhin nichts passiert, starte die Container neu:

docker compose restart

Note

Beim ersten Start legt Wiki.js interne Strukturen in der Datenbank an. Dieser Prozess kann je nach Systemleistung bis zu einer Minute dauern.

Keine Verbindung zur Datenbank

Wenn im Log ein Hinweis wie connection refused oder database does not exist erscheint:

Status prüfen:
```
docker compose ps
```
Der Container wiki-postgres muss healthy sein.
Log anzeigen:
```
docker logs -f wiki-postgres
```
Wenn Fehler zur Anmeldung oder fehlenden Datenbank erscheinen, überprüfe die Datei .env:
```
nano /srv/wiki/.env
```
Achte besonders auf diese Zeilen:
```
POSTGRES_DB=wikidb
POSTGRES_USER=wikijs
POSTGRES_PASSWORD=<STARKES-PASSWORT>
```
Danach Container neu starten:
```
docker compose down
docker compose up -d
```

Änderungen werden nicht gespeichert

Wenn Seiten oder Einstellungen verschwinden, prüfe die Dateirechte im Datenverzeichnis:

ls -ld /srv/wiki/data

Bei falschen Berechtigungen korrigieren:

chown -R 1000:1000 /srv/wiki/data
chmod -R 755 /srv/wiki/data
docker compose restart

Tip

Wiki.js speichert Inhalte direkt auf der Festplatte. Fehlende Schreibrechte verhindern Änderungen oder Uploads.

Wiki.js startet nicht automatisch

Nach einem Neustart von Proxmox oder des Hosts bleibt der Wiki-Container möglicherweise gestoppt.
Setze den Autostart im Container:

pct set <CTID> -onboot 1

Alternativ den Docker-Dienst prüfen:

systemctl status docker

Wenn Docker nicht läuft:

systemctl enable --now docker

Regelmäßige Wartung

Damit das Wiki dauerhaft stabil bleibt, solltest du es monatlich prüfen und aktualisieren:

apt update && apt upgrade -y
docker compose pull
docker compose up -d

Überprüfe danach kurz, ob die Seite erreichbar ist und die Anmeldung funktioniert.
Sichere regelmäßig das Verzeichnis /srv/wiki/data in dein Backup-System (z. B. Kopia oder externes NAS).

👉 Screenshot geeignet: Terminalausgabe mit docker ps (beide Container „Up“)

Ergebnis

Nach Abschluss dieser Schritte läuft Wiki.js vollständig integriert im Homelab.
Der Dienst ist stabil, über HTTPS abgesichert und in dein bestehendes System eingebunden.
Du hast ein modernes, selbst gehostetes Wiki, das alle deine Projekte, Anleitungen und Team-Notizen zentral verwaltet – unabhängig von externen Plattformen.

Dein Setup besteht nun aus zwei Containerdiensten:

wiki-postgres für die Datenbank
wikijs für die Weboberfläche

Beide starten automatisch, sobald der Host aktiv ist.
Der Zugriff erfolgt komfortabel über die Subdomain https://wiki.deinedomain.tld.

Dank der Proxy-Einbindung ist die Verbindung verschlüsselt, und durch das eigene Benutzer- und Rollensystem bleibt der Zugriff auf dein Wissen sicher und kontrolliert.
Du kannst Inhalte strukturieren, Dokumentationen erstellen und dein gesamtes Wissen in Markdown pflegen – alles innerhalb deiner eigenen Infrastruktur.

👉 Screenshot geeignet: Browserfenster mit Wiki.js-Dashboard und geöffneter Startseite

Damit ist der Free-Bereich von Kapitel 14 abgeschlossen.
Im nächsten Teil (Premium) erweitern wir das System um Rollenmanagement, Integration mit Gitea und Nextcloud sowie automatisierte Benutzerrechte und gemeinsame Projektstrukturen.

18 KiB Raw Blame History Unescape Escape