From 0a18fc5db8488747e001d184119caa5c6caf2383 Mon Sep 17 00:00:00 2001
From: michael <michael@dragons-at-work.de>
Date: Sat, 16 Aug 2025 20:37:57 +0200
Subject: [PATCH] =?UTF-8?q?Installation=20hinzugef=C3=BCgt?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Installation.md | 442 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 442 insertions(+)
 create mode 100644 Installation.md

diff --git a/Installation.md b/Installation.md
new file mode 100644
index 0000000..93b6898
--- /dev/null
+++ b/Installation.md
@@ -0,0 +1,442 @@
+# Installation
+
+## Was ist furt
+
+Furt besteht aus vier Hauptkomponenten:
+
+**1. Lua-Anwendung** (`src/main.lua`, `src/auth.lua`, `src/routes/`)
+- HTTP-Server basierend auf lua-socket
+- Request-Routing und Authentifizierungs-Logik
+- Benötigt lua-socket und lua-cjson Module
+
+**2. Konfigurationssystem** (`config/furt.conf`)
+- nginx-style Multi-Tenant-Konfiguration (ein Dienst für mehrere Websites)
+- API-Keys mit individuellen SMTP-Einstellungen
+- Trennung zwischen öffentlicher Konfiguration und vertraulichen Daten
+
+**3. Dienst-Integration**
+- systemd-Unit (Linux) oder rc.d-Skript (BSD)
+- Automatischer Start nach System-Boot
+- Prozess-Verwaltung und Protokollierung
+
+**4. Verzeichnis-Layout**
+- Konfigurations-Verzeichnis für furt.conf und vertrauliche Daten
+- Log-Verzeichnis für furt-spezifische Protokolle
+- Anwendungs-Verzeichnis für Lua-Quelldateien
+
+## Systemanforderungen verstehen
+
+### Lua 5.1 Requirement
+
+Furt nutzt Lua 5.1 aus Kompatibilitätsgründen mit OpenBSD. OpenBSD Packages standardisieren auf Lua 5.1, während FreeBSD und Linux-Distributionen oft Lua 5.4 anbieten. Lua 5.1 funktioniert auf allen Zielplattformen und gewährleistet einheitliche Syntax.
+
+### Warum ein eigener Benutzer
+
+Furt läuft als `_furt` Benutzer für Dienst-Isolation:
+- **Least-Privilege-Prinzip:** Minimale Systemrechte
+- **Prozess-Isolation:** Kein Zugriff auf andere Dienst-Daten
+- **Sicherheits-Grenze:** Bei Kompromittierung begrenzte Auswirkungen
+
+Der Unterstrich-Prefix markiert System-Benutzer (Konvention).
+
+### Warum diese Verzeichnis-Struktur
+
+**Konfigurations-Verzeichnis:** 
+- BSD: `/usr/local/etc/furt/` (Package-Namensraum)
+- Linux: `/etc/furt/` (Einheitlicher Namensraum)
+
+**Log-Verzeichnis:** `/var/log/furt/`
+- Standard-Pfad für System-Logs
+
+**Anwendungs-Verzeichnis:** `/usr/local/share/furt/`
+- Schreibgeschützte Programm-Dateien
+- Getrennt von Konfiguration und Protokollen
+- Standard-Location für Architektur-unabhängige Daten
+
+### Berechtigungs-Modell
+
+**Konfigurations-Dateien:** 644 root:root (644 root:wheel auf BSD)
+- Lesbar für Dienst, nicht änderbar
+- System-Administrator kann Konfiguration bearbeiten
+
+**Vertrauliche Daten:** 600 root:root  
+- Nur Root-Lesezugriff
+- API-Keys und SMTP-Passwörter isoliert
+
+**Protokolle:** 755 _furt:_furt
+- Dienst kann eigene Protokolle schreiben
+- Andere Benutzer können Protokolle lesen (für Debugging)
+
+## Distributions-spezifische Layouts
+
+### BSD-Familie (OpenBSD/FreeBSD)
+
+**Philosophie:** Strikte Trennung Base-System und Packages
+- Base-System: `/etc/`, `/usr/bin/`, `/usr/lib/`
+- Packages: `/usr/local/etc/`, `/usr/local/bin/`, `/usr/local/lib/`
+
+Packages berühren niemals Base-System-Dateien. Updates des Base-Systems beeinflussen keine Package-Konfigurationen.
+
+**furt-Layout:**
+```
+/usr/local/etc/furt/furt.conf    # Package-Konfigurations-Namensraum
+/usr/local/share/furt/           # Anwendungs-Dateien  
+/var/log/furt/                   # Standard Log-Location
+```
+
+### Linux-Familie (Debian/Arch)
+
+**Philosophie:** Einheitlicher Namensraum für alles
+- Base-System und Packages: beide nutzen `/etc/`, `/usr/bin/`
+- Package-Manager verwaltet Konflikte zentral
+
+**furt-Layout:**
+```
+/etc/furt/furt.conf              # Einheitlicher Konfigurations-Namensraum
+/usr/local/share/furt/           # Anwendungs-Dateien
+/var/log/furt/                   # Standard Log-Location  
+```
+
+**Weitere Informationen zu Diensten:** Siehe jeweilige Distributions-Dokumentation:
+- [OpenBSD rc.d Handbuch](https://man.openbsd.org/rc.d)
+- [FreeBSD rc Handbuch](https://docs.freebsd.org/en/articles/rc-scripting/)
+- [systemd Dokumentation](https://systemd.io/)
+
+## Manuelle Installation Schritt für Schritt
+
+### 1. Abhängigkeiten installieren
+
+```bash
+# OpenBSD (lua 5.1 ist Standard)
+pkg_add lua lua-socket lua-cjson
+
+# FreeBSD
+pkg install lua51 lua51-luasocket lua51-lua-cjson
+
+# Debian/Ubuntu  
+apt install lua5.1 lua-socket lua-cjson
+
+# Arch
+pacman -S lua51 lua51-socket lua51-cjson
+```
+
+### 2. Dienst-Benutzer erstellen
+
+```bash
+# BSD-Systeme (wheel-Gruppe für administrative Tasks)
+useradd -s /bin/false -d /nonexistent -g wheel _furt
+
+# Linux-Systeme (eigene Gruppe)
+useradd -r -s /bin/false -d /nonexistent _furt
+```
+
+**Warum diese Parameter:**
+- `-s /bin/false`: Kein Shell-Login möglich
+- `-d /nonexistent`: Kein Home-Verzeichnis
+- `-r`: System-Account (Linux)
+
+### 3. Verzeichnis-Struktur erstellen
+
+```bash
+# BSD-Systeme
+mkdir -p /usr/local/etc/furt/secrets
+mkdir -p /usr/local/share/furt  
+mkdir -p /var/log/furt
+
+# Linux-Systeme
+mkdir -p /etc/furt/secrets
+mkdir -p /usr/local/share/furt
+mkdir -p /var/log/furt
+```
+
+### 4. Berechtigungen setzen
+
+```bash
+# Konfigurations-Verzeichnis: Root-owned, allgemein lesbar
+# BSD
+chown -R root:wheel /usr/local/etc/furt
+chmod 755 /usr/local/etc/furt
+chmod 600 /usr/local/etc/furt/secrets
+
+# Linux  
+chown -R root:root /etc/furt
+chmod 755 /etc/furt
+chmod 600 /etc/furt/secrets
+
+# Log-Verzeichnis: Dienst-owned
+chown -R _furt:_furt /var/log/furt
+chmod 755 /var/log/furt
+
+# Anwendungs-Verzeichnis: Root-owned, allgemein lesbar
+chown -R root:root /usr/local/share/furt
+chmod 755 /usr/local/share/furt
+```
+
+### 5. Anwendungs-Dateien kopieren
+
+```bash
+# Quell-Dateien ins Anwendungs-Verzeichnis
+cp -r src/ /usr/local/share/furt/
+cp -r config/ /usr/local/share/furt/
+
+# Lua-Dateien ausführbar machen
+chmod +x /usr/local/share/furt/src/main.lua
+```
+
+### 6. Konfiguration erstellen
+
+```bash
+# BSD-Systeme
+cp /usr/local/share/furt/config/furt.conf.example /usr/local/etc/furt/furt.conf
+
+# Linux-Systeme
+cp /usr/local/share/furt/config/furt.conf.example /etc/furt/furt.conf
+```
+
+**Wichtig:** Die nginx-style Konfiguration wird von `src/config_parser.lua` geparst. Lua kann nginx-Syntax nicht direkt lesen - der config_parser konvertiert sie in Lua-Tabellen.
+
+Siehe [Configuration.md](Configuration.md) für Konfigurations-Details.
+
+### 7. Dienst-Integration
+
+#### OpenBSD (rc.d)
+```bash
+# Dienst-Skript erstellen
+cat > /etc/rc.d/furt << 'EOF'
+#!/bin/ksh
+daemon="/usr/local/bin/lua"
+daemon_args="/usr/local/share/furt/src/main.lua"
+daemon_user="_furt"
+daemon_cwd="/usr/local/share/furt"
+. /etc/rc.d/rc.subr
+rc_cmd $1
+EOF
+
+chmod +x /etc/rc.d/furt
+```
+
+#### FreeBSD (rc.d)
+```bash
+# Dienst-Skript erstellen
+cat > /usr/local/etc/rc.d/furt << 'EOF'  
+#!/bin/sh
+. /etc/rc.subr
+name="furt"
+rcvar="furt_enable"
+command="/usr/local/bin/lua51"
+command_args="/usr/local/share/furt/src/main.lua"
+furt_user="_furt"
+furt_chdir="/usr/local/share/furt"
+load_rc_config $name
+run_rc_command "$1"
+EOF
+
+chmod +x /usr/local/etc/rc.d/furt
+```
+
+#### Linux (systemd)
+```bash
+# Dienst-Unit erstellen
+cat > /etc/systemd/system/furt.service << 'EOF'
+[Unit]
+Description=Furt API Gateway
+After=network.target
+
+[Service]
+Type=simple
+User=_furt
+Group=_furt
+WorkingDirectory=/usr/local/share/furt
+ExecStart=/usr/bin/lua5.1 src/main.lua
+Restart=always
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+systemctl daemon-reload
+```
+
+### 8. Dienst aktivieren und starten
+
+```bash
+# OpenBSD
+rcctl enable furt
+rcctl start furt
+
+# FreeBSD
+sysrc furt_enable="YES"  
+service furt start
+
+# Linux
+systemctl enable furt
+systemctl start furt
+```
+
+### 9. Funktionstest
+
+```bash
+# Dienst-Status
+# OpenBSD: rcctl check furt
+# FreeBSD: service furt status
+# Linux: systemctl status furt
+
+# HTTP-Endpunkt
+curl http://localhost:7811/health
+```
+
+Erwartete Antwort:
+```json
+{"status":"healthy","service":"furt-lua","version":"1.0.0"}
+```
+
+## Hilfsskripte (Optional)
+
+Diese manuellen Schritte lassen sich durch modulare Hilfsskripte automatisieren:
+
+- **`setup-user.sh`** - Erstellt _furt Benutzer mit korrekten Parametern
+- **`setup-directories.sh`** - Erstellt Verzeichnis-Struktur mit Berechtigungen  
+- **`setup-config.sh`** - Kopiert Konfigurations-Template zum richtigen Pfad
+- **`setup-service.sh`** - Installiert distributions-spezifische Dienst-Dateien
+- **`install.sh`** - Orchestriert alle Hilfsskripte mit Distributions-Erkennung
+
+Die Hilfsskripte führen exakt die oben beschriebenen manuellen Schritte aus.
+
+## Fehlerbehandlung
+
+### Konfigurations-Syntax prüfen
+
+**Kommando:**
+```bash
+# BSD-Systeme
+cd /usr/local/share/furt && lua src/config_parser.lua
+
+# Linux-Systeme
+cd /usr/local/share/furt && lua5.1 src/config_parser.lua
+```
+
+**Erwartete Ausgabe bei korrekter Konfiguration:**
+```
+Loading config from: /usr/local/etc/furt/furt.conf
+Furt Multi-Tenant Configuration Loaded:
+  Server: 127.0.0.1:7811
+  Log Level: info
+  Default SMTP: mail.dragons-at-work.de
+  API Key: Hugo Frontend -> admin@dragons-at-work.de
+  Total API Keys: 1
+```
+
+**Typische Fehlermeldungen:**
+
+*Syntax-Fehler in furt.conf:*
+```
+lua: src/config_parser.lua:45: Invalid line format at line 12: invalid syntax here
+```
+→ Prüfe Zeile 12 auf fehlende `=` oder ungültige Zeichen
+
+*Fehlende API-Keys:*
+```
+lua: src/config_parser.lua:78: API key 'hugo-key' missing mail_to
+```
+→ `mail_to` Parameter in der entsprechenden `[api_key "hugo-key"]` Sektion hinzufügen
+
+*Ungültige SMTP-Konfiguration:*
+```
+Warning: No default SMTP configured, using localhost:25
+```
+→ `[smtp_default]` Sektion vervollständigen
+
+### Prozess läuft nicht
+
+**Diagnose-Kommandos:**
+```bash
+# Protokoll-Dateien prüfen
+tail -f /var/log/furt/furt.log
+
+# Manueller Start für Debugging
+# BSD-Systeme
+cd /usr/local/share/furt && doas -u _furt lua src/main.lua
+
+# Linux-Systeme  
+cd /usr/local/share/furt && sudo -u _furt lua5.1 src/main.lua
+```
+
+**Erwartete Ausgabe bei erfolgreichem Start:**
+```
+Loading config from: /usr/local/etc/furt/furt.conf
+Furt Multi-Tenant Configuration Loaded:
+  Server: 127.0.0.1:7811
+  API Keys: 1
+Furt HTTP-Server started on 127.0.0.1:7811
+API-Key authentication: ENABLED
+Press Ctrl+C to stop
+```
+
+**Typische Fehlermeldungen:**
+
+*Port bereits belegt:*
+```
+lua: src/main.lua:156: Failed to bind to 127.0.0.1:7811
+```
+→ Port 7811 bereits verwendet. Alternative Port in `[server]` Sektion setzen oder blockierenden Prozess beenden:
+```bash
+netstat -an | grep 7811
+kill $(lsof -t -i:7811)
+```
+
+*Fehlende Lua-Module:*
+```
+lua: src/main.lua:3: module 'socket' not found
+```
+→ lua-socket Package installieren (siehe Schritt 1)
+
+*Berechtigungs-Probleme:*
+```
+lua: src/config_parser.lua:15: Could not open config file: /usr/local/etc/furt/furt.conf
+```
+→ Konfigurationsdatei existiert nicht oder falsche Berechtigungen
+
+### Berechtigungs-Probleme reparieren
+
+```bash
+# Datei-Eigentümerschaft prüfen
+# BSD
+ls -la /usr/local/etc/furt/
+ls -la /var/log/furt/
+
+# Linux
+ls -la /etc/furt/
+ls -la /var/log/furt/
+
+# Bei Bedarf Berechtigungen reparieren (siehe Schritt 4)
+# Häufigster Fix: Log-Verzeichnis für _furt Benutzer schreibbar machen
+chown -R _furt:_furt /var/log/furt/
+```
+
+### HTTP-Endpunkt nicht erreichbar
+
+**Verbindungstest:**
+```bash
+# Lokaler Test
+curl -v http://localhost:7811/health
+
+# Netzwerk-Test (von anderem Rechner)
+curl -v http://SERVER_IP:7811/health
+```
+
+**Mögliche Ursachen:**
+- Firewall blockiert Port 7811
+- furt läuft nur auf 127.0.0.1 (localhost) statt 0.0.0.0
+- Dienst läuft nicht (siehe Prozess-Diagnose oben)
+
+**Firewall-Konfiguration:**
+```bash
+# OpenBSD: /etc/pf.conf erweitern
+pass in on egress proto tcp to port 7811
+
+# Linux: iptables oder ufw
+ufw allow 7811
+```
\ No newline at end of file