Homelab--Bratonein-Kontrollzentrum--Tutorial/Kapitel 14/Free Rohtext.md

# 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.

```bash
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.

```bash
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.

```bash
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:

```bash
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.

```bash
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.

```bash
nano .env
```

Inhalt einfügen, **<STARKES-PASSWORT>** ersetzen, speichern (STRG+O, Enter) und schließen (STRG+X):

```env
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).

```bash
nano docker-compose.yaml
```

Inhalt einfügen → speichern → schließen:

```yaml
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.

```bash
docker compose up -d
docker compose ps
```

Logs ansehen, wenn etwas hängt:

```bash
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:

1. **Datenbankverbindung** ist bereits durch Umgebungsvariablen gesetzt (PostgreSQL).  
2. **Admin-Benutzer** anlegen (Benutzername, E-Mail, starkes Passwort).  
3. **Sprache** auf **Deutsch**, **Zeitzone** auf **Europe/Berlin** stellen.  
4. **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

1. Öffne das Dashboard des **Nginx Proxy Manager**.  
2. Klicke auf **Add Proxy Host**.  
3. 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.

### Schritt 11 – Funktionstest (HTTPS, Login, Inhalte)

#### 1. Web-Zugriff prüfen
Rufe im Browser auf:
```
https://wiki.deinedomain.tld
```
Die Login-/Startseite muss ohne Warnung (Schloss-Symbol) laden.

#### 2. Admin-Login
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:
> ```bash
> docker logs -f wikijs
> docker logs -f wiki-postgres
> ```

### Schritt 11 – Funktionstest (HTTPS, Login, erste Seite)

1. **Aufruf prüfen**  
   Öffne im Browser:
   ```
   https://wiki.deinedomain.tld
   ```
   Die Seite muss ohne Warnung (Schloss-Symbol) laden.

2. **Login testen**  
   Mit dem Admin-Konto anmelden.  
   Menü öffnen → **Administration → Benutzer** → dein Admin muss gelistet sein.

3. **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:

1. Prüfe, ob die Container laufen:
   ```bash
   docker ps
   ```
   Wenn `wikijs` oder `wiki-postgres` fehlen, starte sie neu:
   ```bash
   docker compose up -d
   ```
2. 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:

```bash
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:

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

### Änderungen werden nicht gespeichert

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

```bash
ls -ld /srv/wiki/data
```

Bei falschen Berechtigungen korrigieren:
```bash
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:

```bash
pct set <CTID> -onboot 1
```

Alternativ den Docker-Dienst prüfen:
```bash
systemctl status docker
```
Wenn Docker nicht läuft:
```bash
systemctl enable --now docker
```

### Regelmäßige Wartung

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

```bash
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.