diff --git a/Kapitel 14/Free Rohtext.md b/Kapitel 14/Free Rohtext.md new file mode 100644 index 0000000..c888663 --- /dev/null +++ b/Kapitel 14/Free Rohtext.md @@ -0,0 +1,552 @@ +# 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/` 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, **** ersetzen, speichern (STRG+O, Enter) und schließen (STRG+X): + +```env +TZ=Europe/Berlin +POSTGRES_DB=wikidb +POSTGRES_USER=wikijs +POSTGRES_PASSWORD= + +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://:3000 +``` + +👉 **Screenshot geeignet:** Browser mit Wiki.js-Setupseite unter `http://:3000` + +### Schritt 8 – Erstkonfiguration im Browser + +Rufe `http://: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://: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= + ``` + 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 -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. \ No newline at end of file