Kapitel 16/Tutorial.md aktualisiert

Kapitel 16/Tutorial.md

@@ -3,63 +3,73 @@
 ---
 
 🎯 Ziel  
-Wir bauen ein eigenes **Wiki** mit **Wiki.js**.  
-Am Ende ist das Wiki über eine eigene Domain erreichbar, per HTTPS abgesichert und mit einem Admin-Account eingerichtet.
+Wir setzen **Wiki.js** im Debian‑12‑LXC mit Docker stabil und wiederholbar auf.  
+Am Ende: HTTPS‑Zugriff über Subdomain, Admin angelegt, Registrierung abgesichert.
 
 ---
 
 📖 Warum Wiki.js?  
-- ❌ Lose Textdateien sind schnell unübersichtlich  
-- ❌ Externe Tools bedeuten Abhängigkeit von Dritten  
-- ✅ Wiki.js ist modern, unterstützt Markdown, hat Rollen- und Rechteverwaltung  
-- ✅ Läuft vollständig im eigenen Homelab und ist auch offline erreichbar  
+- ✅ Moderne Weboberfläche, Markdown, Suche  
+- ✅ Rechte/Rollen, volle Datenhoheit im Homelab  
+- ✅ Leichtgewichtig per Docker betreibbar
 
 ---
 
 ✅ Voraussetzungen  
-- LXC-Container mit Debian 12 (Bookworm)  
-- Empfohlen: 1 vCPU, 1–2 GB RAM, ≥ 10 GB Speicher  
-- Domain/Subdomain (z. B. `wiki.deinedomain.tld`)  
+- Debian 12 LXC, 1 vCPU, 1–2 GB RAM, ≥ 10 GB Speicher  
+- Domain/Subdomain (z. B. `wiki.deinedomain.tld`)  
 - Nginx Proxy Manager + DynDNS  
-- Internetzugang für den Container  
+- Internetzugang im LXC
 
 ---
 
-## 1️⃣ Container vorbereiten
+## 1️⃣ System & Docker (stabile Variante über das offizielle Docker‑Repo)
+
+**Warum:** Die Debian‑Pakete liefern kein zuverlässiges Compose‑Plugin. Wir binden das **offizielle Docker‑Repository** ein und installieren Docker + Compose einmal richtig.
 
 ```bash
 apt update && apt upgrade -y
 apt install -y ca-certificates curl gnupg lsb-release
+```
+👉 System aktualisieren, Grundpakete für HTTPS‑Repos und Schlüsselverwaltung.
 
+```bash
 mkdir -p /etc/apt/keyrings
 curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+```
+👉 Docker‑GPG‑Schlüssel ablegen (benötigt für verifizierte Pakete).
 
-echo \ 
-  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
-  $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
-
+```bash
+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
 ```
-👉 Wir bringen das System auf den neuesten Stand, fügen das offizielle Docker-Repository hinzu und installieren Docker inklusive Compose.
+👉 Repo einbinden, Paketquellen aktualisieren, **Docker + Compose‑Plugin** installieren.
+
+```bash
+systemctl enable --now docker
+```
+👉 Docker beim Start aktivieren und sofort starten.
 
 ```bash
 mkdir -p /srv/wiki
 cd /srv/wiki
 ```
-👉 Wir legen das Projektverzeichnis `/srv/wiki` an und wechseln hinein. Dort liegen später alle Dateien für das Wiki.
+👉 Projektordner anlegen und hineingehen – hier liegt alles zum Wiki.
 
 ---
 
-## 2️⃣ Projektdateien erstellen
+## 2️⃣ Umgebungsdatei `.env` erstellen
 
-### `.env`
+**Warum:** Zugangsdaten und wiederverwendbare Einstellungen zentral halten.
 
 ```bash
 nano .env
 ```
-👉 Mit `nano` öffnen wir eine neue Datei namens `.env`.  
-Kopiere den folgenden Inhalt hinein:
+👉 Datei öffnen, folgenden Inhalt einfügen, **<STARKES-PASSWORT>** ersetzen, dann **STRG+O**, Enter, **STRG+X**:
 
 ```env
 TZ=Europe/Berlin
@@ -75,18 +85,16 @@ WIKI_DB_NAME=${POSTGRES_DB}
 WIKI_PORT=3000
 ```
 
-👉 Ersetze `<STARKES-PASSWORT>` durch ein sicheres Passwort.  
-Speichern: **STRG+O**, Enter. Beenden: **STRG+X**.
-
 ---
 
-### `docker-compose.yaml`
+## 3️⃣ `docker-compose.yaml` schreiben
+
+**Warum:** Definiert die beiden Dienste (Datenbank + Wiki) samt Persistenz und Startreihenfolge.
 
 ```bash
 nano docker-compose.yaml
 ```
-👉 Wir erstellen die Hauptdatei für die Container.  
-Trage den folgenden Inhalt ein:
+👉 Inhalt einfügen → speichern (**STRG+O**) → schließen (**STRG+X**):
 
 ```yaml
 version: "3.9"
@@ -96,6 +104,11 @@ services:
     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:
@@ -125,79 +138,70 @@ services:
     volumes:
       - ./data/wikijs:/var/wiki
 ```
-
-👉 Zwei Container: **Postgres** für die Datenbank und **Wiki.js** für das Webinterface.  
-Die Daten werden im Ordner `data` gespeichert.
-
-Speichern und schließen wie oben.
+👉 Persistenz: `./data/postgres` (DB‑Daten) und `./data/wikijs` (Uploads/Cache). Healthcheck sorgt für korrekte Startreihenfolge.
 
 ---
 
-## 3️⃣ Container starten und prüfen
+## 4️⃣ Start & Status prüfen
 
 ```bash
 docker compose up -d
 ```
-👉 Startet beide Container im Hintergrund.
+👉 Beide Container im Hintergrund starten.
 
 ```bash
 docker compose ps
 ```
-👉 Listet die Container auf. Beide müssen `Up` anzeigen, Postgres nach kurzer Zeit `healthy`.
-
----
-
-## 4️⃣ Proxy Host in Nginx Proxy Manager
-
-1. Im Browser Nginx Proxy Manager öffnen  
-2. Neuer Proxy Host  
-   - Domain: `wiki.deinedomain.tld`  
-   - Forward Hostname/IP: `<LXC-IP>`  
-   - Forward Port: `3000`  
-   - Websockets aktivieren  
-3. SSL → Neues Zertifikat anfordern, „Force SSL“, „HTTP/2“ und „HSTS“ aktivieren  
-4. Speichern  
-
-👉 Ab jetzt ist das Wiki über `https://wiki.deinedomain.tld` erreichbar.
-
----
-
-## 5️⃣ Erstkonfiguration im Browser
-
-Aufrufen:  
-```
-https://wiki.deinedomain.tld
-```
-
-- Admin-Benutzer erstellen (Name, Passwort, E-Mail)  
-- Sprache: Deutsch  
-- Zeitzone: Europe/Berlin  
-- Registrierung: „Nur Einladung“ oder „Admin Approval“  
-- Erste Startseite anlegen  
-
-👉 Dein Wiki ist betriebsbereit.
-
----
-
-⚠️ Fehlerbehebung  
+👉 Status prüfen: beide `Up`; `wiki-postgres` wird nach kurzer Zeit `healthy`.
 
+Logs bei Problemen:
 ```bash
 docker logs -f wikijs
+# in neuem Terminal/Fenster ggf. zusätzlich:
 docker logs -f wiki-postgres
 ```
-👉 Mit diesen Befehlen siehst du die Logdateien.
-
-- 502-Error → Container läuft nicht oder Websockets in NPM vergessen  
-- Setup hängt → Werte in `.env` prüfen  
-- IPv6-Probleme → AAAA-Record entfernen  
-- Uploads fehlen → Schreibrechte im `data`-Ordner prüfen  
+👉 Live‑Logs helfen bei DB‑Verbindungsfehlern oder Startproblemen.
 
 ---
 
-✅ Ergebnis  
-- Wiki.js läuft in Docker (Debian 12 LXC)  
-- Zugriff über `https://wiki.deinedomain.tld`  
-- Admin-Benutzer erstellt und Registrierung gesichert  
+## 5️⃣ Reverse‑Proxy im Nginx Proxy Manager
+
+**Warum:** Öffentlich per Domain & HTTPS erreichbar machen.
+
+1. NPM öffnen → **Proxy Host hinzufügen**  
+2. **Domain**: `wiki.deinedomain.tld`  
+3. **Forward Host/IP**: `<LXC-IP>` · **Port**: `3000`  
+4. **Websockets aktivieren**  
+5. **SSL**: Neues Zertifikat (Let’s Encrypt) → **Force SSL**, **HTTP/2**, **HSTS** aktivieren  
+6. Speichern
+
+👉 Test: `https://wiki.deinedomain.tld` im Browser aufrufen.
+
+---
+
+## 6️⃣ Erstkonfiguration in Wiki.js
+
+1. Admin‑Benutzer anlegen (Benutzername, Passwort, E‑Mail)  
+2. Sprache **Deutsch**, Zeitzone **Europe/Berlin** setzen  
+3. Registrierung: **Nur Einladung** oder **Admin Approval**  
+4. Erste **Startseite** anlegen (Projektübersicht)
+
+👉 Danach ist das Wiki einsatzbereit.
+
+---
+
+## ⚠️ Fehlerbehebung (kurz & präzise)
+- **502 via NPM** → Container laufen? Port 3000 korrekt? **Websockets** an?  
+- **Setup hängt/DB‑Fehler** → Werte in `.env` prüfen; Logs oben ansehen  
+- **IPv6‑Probleme** → AAAA‑Record testweise entfernen  
+- **Uploads fehlen** → Schreibrechte in `./data/wikijs` prüfen
+
+---
+
+## ✅ Ergebnis
+- Wiki.js läuft stabil in Docker (Debian 12 LXC)  
+- Zugriff: `https://wiki.deinedomain.tld` (HTTPS)  
+- Admin angelegt, Registrierung eingeschränkt  
 - Daten persistent gespeichert
 
 ➡️ Nächstes Kapitel: **Netdata (Monitoring)**