Home aktualisiert

2025-09-03 13:44:51 +02:00 · 2025-09-03 13:44:51 +02:00 · d61a8e2aee
commit d61a8e2aee
parent 3841afdeb4
1 changed files with 571 additions and 82 deletions
--- a/Home.md
+++ b/Home.md
@ -1,111 +1,600 @@
-# Furt API Gateway
+# furt Installation Guide

-**Pure Lua HTTP-Server für digitale Souveränität**
+**Lua API-Gateway für digitale Souveränität**

-Furt ist ein minimalistisches, multi-tenant API-Gateway basierend auf Lua 5.1. Der gesamte Code ist in unter 1000 Zeilen Lua geschrieben und damit vollständig nachvollziehbar.
+## Source-Code beschaffen

-## Features
+### Git-Repository clonen

- **Multi-Tenant Mail-Routing** - Ein Gateway für viele Websites
- **API-Key-basierte Authentifizierung** - Granulare Berechtigungen pro Client  
- **Rate Limiting** - Schutz vor Missbrauch
- **CORS-Support** - Frontend-Integration
- **nginx-style Konfiguration** - Vertraute Syntax für Admins
- **Distribution-agnostic** - OpenBSD, Debian, Arch, FreeBSD Support
+furt-Quellen aus dem Dragons@Work-Repository beschaffen:

-## Quick Start
-
-### 1. Installation
 ```bash
-# Git-basierte Installation (empfohlen für Development)
-git clone https://github.com/dragons-at-work/furt.git
-cd furt
-./install.sh
-
-# Package-basierte Installation (empfohlen für Production)
-curl -O https://releases.../furt-api-gateway-v1.0.0.tar.gz
-tar xzf furt-api-gateway-v1.0.0.tar.gz
-cd furt-api-gateway-v1.0.0
-./install.sh
+# Repository clonen
+git clone https://smida.dragons-at-work.de/DAW/furt.git /tmp/furt-source
+cd /tmp/furt-source
 ```

-### 2. Basis-Konfiguration
+**Repository-Struktur validieren:**
 ```bash
-# Config-Template kopieren
-# BSD-Systeme: Packages gehören nach /usr/local/etc/ (klare Trennung base/ports)
-doas cp config/furt.conf.example /usr/local/etc/furt/furt.conf  # OpenBSD/FreeBSD
+# Erforderliche Verzeichnisse prüfen
+ls -la src/main.lua config/furt.conf.example scripts/start.sh integrations/

-# Linux-Systeme: Alles nach /etc/ (einheitlicher Namespace)
-sudo cp config/furt.conf.example /etc/furt/furt.conf            # Debian/Arch
-
-# API-Keys und SMTP konfigurieren
-# doas = OpenBSD-Standard (minimaler sudo-Ersatz, weniger Angriffsfläche)
-doas nano /usr/local/etc/furt/furt.conf  # OpenBSD/FreeBSD
-
-# sudo = Linux-Standard (komplexer, aber bekannt)
-sudo nano /etc/furt/furt.conf            # Debian/Arch
+# Erwartete Struktur:
+# src/          - Lua-Quellcode
+# config/       - Konfigurationsbeispiele
+# scripts/      - Helper-Scripts (start.sh)
+# integrations/ - merkwerk-Integration
+# docs/         - Dokumentation
+# VERSION       - Versions-Information
 ```

-### 3. Service starten
-```bash
-# BSD-Systeme: Native Service-Management (kein systemd)
-doas rcctl enable furt && doas rcctl start furt     # OpenBSD (rcctl = OpenBSD service manager)
-doas service furt enable && doas service furt start # FreeBSD (rc.conf-basiert)
+**Git-Installation falls erforderlich:**

-# Linux-Systeme: systemd als Standard
-# systemd = umfangreich aber einheitlich über Distributionen
-sudo systemctl enable furt && sudo systemctl start furt
+*OpenBSD:*
+```bash
+doas pkg_add git
 ```

-### 4. Testen
+*Debian/Ubuntu:*
 ```bash
-curl http://localhost:8080/health
+apt install git
 ```

-## Navigation
+## Systemanforderungen verstehen

-### Installation & Setup
- **[Installation](Installation.md)** - Vollständige Installationsanleitung
- **[Konfiguration](Configuration.md)** - Config-System Dokumentation
- **[Troubleshooting](Troubleshooting.md)** - Häufige Probleme
+### Lua-Runtime Anforderungen

-### Development
- **[Development Setup](Development.md)** - Lokale Entwicklungsumgebung
- **[API Documentation](API-Documentation.md)** - Endpunkte und Verwendung
- **[Contributing](Contributing.md)** - Beitrag zum Projekt
+furt basiert auf reinem Lua 5.1 ohne C-Erweiterungen für maximale Portabilität auf freien Systemen. Die Architektur nutzt Lua-Module für HTTP-Server-Funktionalität statt komplexer C-Bibliotheken.

-### Current Status
+**Erforderliche Lua-Module:**
+- `socket` - TCP-Server-Implementation für HTTP-Handling
+- `cjson` - JSON-Kodierung für API-Responses ohne externe Parser-Dependencies

-**v1.0.0 Features:**
- ✅ Mail-Service (`POST /v1/mail/send`)
- ✅ Health-Check (`GET /health`) 
- ✅ API-Key Authentication
- ✅ Multi-Tenant Configuration
- ✅ Rate Limiting
- ✅ CORS Support
+**Warum Lua 5.1:** Die PUC-Rio-University-Entwicklung steht außerhalb Corporate-Kontrolle. Lua 5.1 bietet stabile APIs ohne Breaking Changes zwischen Minor-Versionen.

-**Roadmap:**
- 🔄 Comment-Service (sagjan integration)
- 📋 Project-Management-Service (lengan)
- 💳 Payment-Service (wixlaz)
+### Version-Tracking Integration

-## Architecture
+furt integriert `merkwerk` für Selbst-Versionierung und Content-Hashing. Diese Integration ermöglicht eindeutige Versions-Identifikation ohne Git-Dependencies im Produktions-System.

-Furt folgt dem **Service-Separation-Prinzip**:
- **furt** = Service-Discovery-Coordinator 
- **sagjan** = Comments (separate namespace)
- **formular2mail** = Mail-Routing (separate namespace)
+**merkwerk-Funktionen in furt:**
+- Content-basierte Hash-Generierung für Integritäts-Prüfungen
+- VCS-unabhängige Versions-Verfolgung
+- Automatische `.version_history`-Updates bei Änderungen

-Jeder Service behält seine eigene Konfiguration, furt koordiniert nur die Discovery und das Routing.
+### SMTP-Integration

-**Technische Basis:**
- **Lua 5.1** als Implementierungssprache
- **nginx-style Konfiguration** für vertraute Admin-Workflows
- **Multi-OS Support** über distribution-spezifische Package-Layouts
- **Socket-basierter HTTP-Server** ohne externe Dependencies
+furt leitet Formular-Daten an bestehende SMTP-Server weiter statt eigene Mail-Server-Funktionalität zu implementieren. Diese Architektur trennt API-Gateway von Mail-Transport-Verantwortlichkeiten.

---
+**SMTP-Requirements:**
+- Funktionierender SMTP-Server (intern oder extern)
+- SMTP-Authentifizierung (USERNAME/PASSWORD)
+- SSL/TLS-Unterstützung für sichere Verbindungen

-**Projekt:** [Dragons@Work Digital Sovereignty](https://dragons-at-work.de)  
-**Repository:** [Forgejo](https://smida.dragons-at-work.de/DAW/furt) | [GitHub Mirror](https://github.com/dragons-at-work/furt)  
-**License:** Apache 2.0
+## Installation verstehen
+
+### Verzeichnis-Layout nach POSIX-Standards
+
+furt folgt etablierten Unix-Konventionen für selbst-installierte Software:
+
+**OpenBSD/FreeBSD-Layout:**
+```
+/usr/local/bin/furt                    # Haupt-Executable
+/usr/local/share/furt/                 # Source-Code-Bibliothek
+/usr/local/share/furt/src/             # Lua-Module
+/usr/local/share/furt/config/          # Config-Beispiele
+/usr/local/share/furt/integrations/    # merkwerk-Integration
+/usr/local/etc/furt/                   # Produktions-Konfiguration
+/var/log/furt/                         # Log-Dateien
+```
+
+**Linux-Layout:**
+```
+/usr/local/bin/furt                    # Haupt-Executable
+/usr/local/share/furt/                 # Source-Code-Bibliothek
+/usr/local/share/furt/src/             # Lua-Module
+/usr/local/share/furt/config/          # Config-Beispiele
+/usr/local/share/furt/integrations/    # merkwerk-Integration
+/etc/furt/                             # Produktions-Konfiguration
+/var/log/furt/                         # Log-Dateien
+```
+
+**Warum diese Trennung:** `/usr/local/share/furt/` enthält unveränderlichen Code, `/usr/local/etc/furt/` (oder `/etc/furt/`) maschinenspezifische Konfiguration. Updates überschreiben Code ohne Konfiguration zu beeinflussen.
+
+### Lua-Pfad-Mechanismus
+
+Lua sucht Module über `LUA_PATH`-Environment-Variable. furt erweitert Standard-Pfade um seine Module-Verzeichnisse ohne System-Lua-Installation zu beeinflussen.
+
+**Pfad-Auflösung:**
+1. Aktuelle Verzeichnis (`./config.server` für Development)
+2. furt-Module (`/usr/local/share/furt/?.lua`)
+3. System-Lua-Module (Standard-Pfade)
+
+## Schritt-für-Schritt Installation
+
+### 1. Systemanforderungen prüfen
+
+**Lua-Installation validieren mit automatischer Command-Detection:**
+
+```bash
+# Lua-Command erkennen (plattformspezifisch)
+if command -v lua5.1 >/dev/null 2>&1; then
+    LUA_CMD="lua5.1"
+elif command -v lua >/dev/null 2>&1; then
+    LUA_CMD="lua"
+else
+    echo "Kein Lua gefunden"
+    exit 1
+fi
+
+# Lua-Version prüfen
+$LUA_CMD -v
+
+# Erwartete Ausgabe:
+# Lua 5.1.5  Copyright (C) 1994-2012 Lua.org, PUC-Rio
+
+# Required modules testen
+$LUA_CMD -e "require('socket')"
+$LUA_CMD -e "require('cjson')"
+```
+
+**Warum Command-Detection:** OpenBSD installiert Lua als `lua`, Linux-Distributionen oft als `lua5.1`.
+
+**Fehlende Module installieren:**
+
+*Arch Linux:*
+```bash
+pacman -S lua51-socket lua51-dkjson lua51-sec
+```
+
+*OpenBSD:*
+```bash
+pkg_add lua-socket lua-cjson luasec
+```
+
+*Debian/Ubuntu:*
+```bash
+apt install lua-socket lua-cjson lua-sec
+```
+
+**Warum lua-sec:** furt nutzt SMTP mit SSL/TLS-Verschlüsselung (Port 465). Ohne SSL-Bibliothek schlägt Mail-Versendung fehl.
+
+### 2. Benutzer und Verzeichnisse erstellen
+
+**System-Benutzer für Sicherheit:**
+
+*OpenBSD/FreeBSD:*
+```bash
+# System-spezifische UID wird automatisch zugewiesen
+groupadd _furt
+useradd -g _furt -s /bin/false -d /var/empty _furt
+```
+
+*Linux:*
+```bash
+# --system Flag verwendet niedrige UIDs für System-Dienste
+groupadd --system furt
+useradd --system -g furt -s /bin/false -d /var/empty furt
+```
+
+**Verzeichnis-Struktur anlegen:**
+
+*OpenBSD/FreeBSD:*
+```bash
+mkdir -p /usr/local/etc/furt
+mkdir -p /usr/local/share/furt
+mkdir -p /var/log/furt
+chown _furt:_furt /var/log/furt
+```
+
+*Linux:*
+```bash
+mkdir -p /etc/furt
+mkdir -p /usr/local/share/furt
+mkdir -p /var/log/furt
+chown furt:furt /var/log/furt
+```
+
+### 3. furt-Quellen installieren
+
+**Source-Code kopieren:**
+```bash
+# In furt-source-Verzeichnis (aus Schritt 0)
+cd /tmp/furt-source
+
+# Haupt-Bibliothek installieren
+cp -r src/ /usr/local/share/furt/
+cp -r config/ /usr/local/share/furt/
+cp -r scripts/ /usr/local/share/furt/
+cp -r integrations/ /usr/local/share/furt/
+
+# Versions-Dateien für merkwerk-Integration
+cp VERSION /usr/local/share/furt/
+cp .version_history /usr/local/share/furt/
+
+# Berechtigungen setzen
+chown -R root:wheel /usr/local/share/furt  # OpenBSD/FreeBSD
+chown -R root:root /usr/local/share/furt   # Linux
+chmod -R 644 /usr/local/share/furt
+find /usr/local/share/furt -type d -exec chmod 755 {} \;
+chmod +x /usr/local/share/furt/scripts/start.sh
+```
+
+**Warum scripts/ inkludieren:** Das `start.sh`-Script löst Service-vs-Interactive-Detection und Lua-Command-Erkennung.
+
+### 4. Startup-Script konfigurieren
+
+**furt nutzt das integrierte `start.sh`-Script für plattformspezifische Anpassungen:**
+
+```bash
+# start.sh-Funktionalität testen
+cd /usr/local/share/furt
+./scripts/start.sh
+
+# Erwartete Ausgabe:
+# Auto-detected lua command: lua
+# Furt HTTP-Server started on 127.0.0.1:7811
+# [...]
+```
+
+**Warum start.sh statt direkter Lua-Aufruf:**
+- Automatische Lua-Command-Detection (lua vs lua5.1)
+- Service-vs-Interactive-Mode-Erkennung
+- Plattformspezifische Pfad-Anpassungen
+- Robuste Daemon-Integration
+
+### 5. Konfiguration verstehen
+
+furt nutzt INI-Format für menschenlesbare Konfiguration ohne komplexe Parser-Dependencies.
+
+**Konfigurations-Struktur:**
+- `[server]` - HTTP-Server-Parameter
+- `[smtp_default]` - Standard-SMTP-Einstellungen
+- `[api_key "name"]` - Mandanten-spezifische API-Schlüssel
+
+**Basis-Konfiguration erstellen:**
+
+*OpenBSD/FreeBSD* - `/usr/local/etc/furt/furt.conf`:
+```ini
+# furt Multi-Mandanten-Konfiguration
+
+[server]
+host = 127.0.0.1
+port = 7811
+log_level = info
+
+[smtp_default]
+host = mail.dragons-at-work.de
+port = 465
+user = noreply@dragons-at-work.de
+password = smtp-password-hier-eintragen
+use_ssl = true
+
+# Dragons@Work Website
+[api_key "daw-frontend-key"]
+name = "Dragons@Work Website"
+permissions = mail:send
+allowed_ips = 127.0.0.1, 10.0.0.0/8, 192.168.0.0/16
+mail_to = admin@dragons-at-work.de
+mail_from = noreply@dragons-at-work.de
+mail_subject_prefix = "[DAW] "
+
+# Monitoring ohne Mail-Weiterleitung
+[api_key "monitoring-health-key"]
+name = "Monitoring Service"
+permissions = health:check
+allowed_ips = 127.0.0.1, 10.0.0.0/8
+```
+
+*Linux* - `/etc/furt/furt.conf`:
+```ini
+# Identische Konfiguration wie oben
+```
+
+**Sicherheits-Berechtigungen für Produktion:**
+
+*OpenBSD/FreeBSD:*
+```bash
+chmod 640 /usr/local/etc/furt/furt.conf
+chown root:_furt /usr/local/etc/furt/furt.conf
+```
+
+*Linux:*
+```bash
+chmod 640 /etc/furt/furt.conf
+chown root:furt /etc/furt/furt.conf
+```
+
+**Testing-Berechtigungen:** Für manuelle Tests als normaler Benutzer temporär lesbare Berechtigungen setzen:
+
+```bash
+# Temporär für Testing
+chmod 644 /usr/local/etc/furt/furt.conf  # OpenBSD/FreeBSD
+chmod 644 /etc/furt/furt.conf            # Linux
+
+# Nach Testing wieder sichern
+chmod 640 /usr/local/etc/furt/furt.conf  # OpenBSD/FreeBSD
+chmod 640 /etc/furt/furt.conf            # Linux
+```
+
+**Oder als Service-User testen:**
+```bash
+# OpenBSD/FreeBSD
+doas -u _furt /usr/local/share/furt/scripts/start.sh
+
+# Linux
+sudo -u furt /usr/local/share/furt/scripts/start.sh
+```
+
+### 6. Service-Integration
+
+**OpenBSD rc.d-Script aus Repository-Template:**
+```bash
+# Template aus Repository verwenden
+cp deployment/openbsd/rc.d-furt /etc/rc.d/furt
+chmod +x /etc/rc.d/furt
+echo "furt_flags=" >> /etc/rc.conf.local
+rcctl enable furt
+```
+
+**Das Template `deployment/openbsd/rc.d-furt` enthält:**
+- Service-vs-Interactive-Detection über `start.sh`
+- Korrekte Daemon-Konfiguration für OpenBSD
+- Prozess-Pattern für `rcctl`-Integration
+
+**Linux systemd-Unit** - `/etc/systemd/system/furt.service`:
+```ini
+[Unit]
+Description=furt Multi-Tenant API Gateway
+After=network.target
+
+[Service]
+Type=simple
+User=furt
+Group=furt
+ExecStart=/usr/local/share/furt/scripts/start.sh start
+WorkingDirectory=/usr/local/share/furt
+Restart=always
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+systemctl daemon-reload
+systemctl enable furt
+```
+
+## Installation validieren
+
+### Service starten und Status prüfen
+
+**OpenBSD:**
+```bash
+rcctl start furt
+rcctl check furt
+```
+
+**Linux:**
+```bash
+systemctl start furt
+systemctl status furt
+```
+
+### Health-Check durchführen
+
+```bash
+curl http://127.0.0.1:7811/health
+```
+
+**Erwartete Response:**
+```json
+{
+  "status": "healthy",
+  "service": "furt-lua",
+  "version": "0.1.1+a1b2c3d4",
+  "content_hash": "sha256:abc123...",
+  "vcs_info": {
+    "type": "git",
+    "hash": "a1b2c3d4",
+    "branch": "main"
+  },
+  "timestamp": 1692634800,
+  "source": "merkwerk",
+  "features": {
+    "smtp_configured": true,
+    "auth_enabled": true,
+    "rate_limiting": true,
+    "merkwerk_integrated": true
+  }
+}
+```
+
+**Was diese Response bedeutet:**
+- `merkwerk_integrated: true` - Versions-Tracking funktioniert
+- `smtp_configured: true` - SMTP-Konfiguration erkannt
+- `content_hash` - Eindeutige Code-Identifikation für Integritäts-Prüfung
+
+### Mail-Funktionalität testen
+
+```bash
+curl -X POST http://127.0.0.1:7811/v1/mail/send \
+  -H "X-API-Key: daw-frontend-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Installation Test",
+    "email": "test@example.com",
+    "subject": "furt Installation erfolgreich",
+    "message": "Das furt API-Gateway ist betriebsbereit."
+  }'
+```
+
+**Erfolgreiche Response:**
+```json
+{
+  "success": true,
+  "message": "Mail sent successfully",
+  "tenant": {
+    "name": "Dragons@Work Website",
+    "recipient": "admin@dragons-at-work.de"
+  }
+}
+```
+
+## Multi-Mandanten-Konfiguration
+
+### Zusätzliche Websites hinzufügen
+
+furt unterstützt mehrere Websites über separate API-Schlüssel mit mandanten-spezifischer Konfiguration.
+
+**Neue Website-Konfiguration hinzufügen:**
+
+```ini
+# Neuen API-Key-Block zur furt.conf hinzufügen
+[api_key "neue-website-key"]
+name = "Neue Website GmbH"
+permissions = mail:send
+allowed_ips = 203.0.113.0/24
+mail_to = kontakt@neue-website.de
+mail_from = noreply@neue-website.de
+mail_subject_prefix = "[Neue Website] "
+```
+
+**Service neu starten für Konfiguration-Reload:**
+
+*OpenBSD:*
+```bash
+rcctl restart furt
+```
+
+*Linux:*
+```bash
+systemctl restart furt
+```
+
+### Mandanten-spezifische SMTP-Server
+
+Einzelne Mandanten können eigene SMTP-Server nutzen statt den Standard-Server:
+
+```ini
+[api_key "kunde-eigener-smtp"]
+name = "Kunde mit eigenem Mail-Server"
+permissions = mail:send
+allowed_ips = 198.51.100.0/24
+mail_to = support@kunde-server.com
+mail_from = noreply@kunde-server.com
+# Überschreibt smtp_default-Einstellungen
+mail_smtp_host = mail.kunde-server.com
+mail_smtp_port = 587
+mail_smtp_user = api@kunde-server.com
+mail_smtp_pass = kunde-smtp-passwort
+mail_smtp_ssl = true
+```
+
+**Warum mandanten-spezifische SMTP:** Unternehmens-Kunden bevorzugen eigene Mail-Server für Branding und Zustellbarkeits-Kontrolle.
+
+## API-Endpunkt-Referenz
+
+### Öffentliche Endpunkte (ohne Authentifizierung)
+
+**GET /health**
+- System-Status und Versions-Information
+- Für Monitoring und Load-Balancer-Health-Checks
+- Response enthält merkwerk-Integration-Status
+
+### Geschützte Endpunkte (benötigen X-API-Key Header)
+
+**POST /v1/mail/send**
+- Formular-zu-Email-Weiterleitung
+- Benötigt `mail:send`-Permission
+- JSON-Request mit name, email, subject, message Feldern
+
+**GET /v1/auth/status**
+- API-Key-Validierung und Permission-Check
+- Für Frontend-Authentifizierungs-Status-Prüfung
+- Response enthält aktive Permissions
+
+## Troubleshooting
+
+### Port 7811 bereits belegt
+
+**Diagnose:**
+```bash
+# OpenBSD/FreeBSD
+netstat -an | grep 7811
+
+# Linux
+ss -tlnp | grep 7811
+lsof -i:7811
+```
+
+**Lösung:** Port in `furt.conf` ändern und Service neu starten.
+
+### Lua-Module nicht gefunden
+
+**Symptom:**
+```bash
+$ furt
+lua5.1: src/main.lua:4: module 'socket' not found
+```
+
+**Diagnose und Lösung:**
+```bash
+# Module-Verfügbarkeit prüfen
+lua5.1 -e "print(package.path)"
+lua5.1 -e "require('socket')"
+
+# Fehlende Module installieren (siehe Schritt 1)
+```
+
+### SMTP-Verbindungsfehler
+
+**Symptom:** Mail-Requests erhalten 500-Fehler mit "SMTP connection failed"
+
+**Diagnose:**
+```bash
+# SMTP-Server-Erreichbarkeit testen
+telnet mail.dragons-at-work.de 465
+
+# TLS-Handshake testen
+openssl s_client -connect mail.dragons-at-work.de:465
+```
+
+**Häufige Ursachen:**
+- Firewall blockiert Ports 465/587
+- Falsche SMTP-Credentials in `furt.conf`
+- SMTP-Server erfordert andere SSL/TLS-Konfiguration
+
+### merkwerk-Integration fehlt
+
+**Symptom:** Health-Check zeigt `"merkwerk_integrated": false`
+
+**Diagnose:**
+```bash
+# merkwerk-Installation prüfen
+which merkwerk
+merkwerk --version
+
+# furt-Verzeichnis auf .version_history prüfen
+ls -la /usr/local/share/furt/.version_history
+```
+
+**Lösung:** merkwerk installieren oder .version_history-Datei erstellen.
+
+### API-Key-Authentifizierung fehlschlägt
+
+**Symptom:** 401 Unauthorized trotz korrektem API-Key
+
+**Diagnose:**
+```bash
+# IP-Adresse des Clients prüfen
+# Muss in allowed_ips der API-Key-Konfiguration stehen
+
+# furt-Logs prüfen
+tail -f /var/log/daemon  # OpenBSD
+journalctl -u furt -f    # Linux
+```
+
+Diese Installation führt zu einem produktions-tauglichen furt-System mit mandanten-fähiger Architektur und merkwerk-basiertem Versions-Tracking.