diff --git a/Installation.md b/Installation.md index a75dca3..68061ee 100644 --- a/Installation.md +++ b/Installation.md @@ -1,620 +1,244 @@ -# furt Installation Guide +# furt Installation -**Lua API-Gateway für digitale Souveränität** +**Lua API-Gateway für mehrere Websites** + +## Getestet unter +- OpenBSD 7.7 +- Debian 12 +- Arch Linux + +## Systemanforderungen verstehen + +furt ist ein HTTP-Server geschrieben in Lua 5.1. Da Lua eine Skriptsprache ist, benötigen wir keine Compilation - der Quellcode läuft direkt auf dem Lua-Interpreter. Drei zusätzliche Module erweitern Lua um die benötigte Funktionalität: + +Das `socket`-Modul stellt TCP-Server-Funktionen bereit. Ohne dieses Modul kann Lua keine eingehenden HTTP-Verbindungen entgegennehmen. Für JSON-Kodierung der API-Antworten nutzt furt entweder `cjson` oder `dkjson` - der Code erkennt automatisch welches verfügbar ist. Das `ssl`-Modul ermöglicht verschlüsselte SMTP-Verbindungen für den Mail-Versand. + +```bash +# OpenBSD installiert alle Module über pkg_add +doas pkg_add lua lua-socket lua-cjson luasec + +# Debian nutzt separate Pakete für jedes Modul +sudo apt install lua5.1 lua-socket lua-cjson lua-sec + +# Arch Linux verwendet lua51-Präfix für Lua 5.1 Pakete +sudo pacman -S lua51 lua51-socket lua51-dkjson lua51-sec +``` + +Arch Linux stellt nur dkjson zur Verfügung, während andere Distributionen cjson nutzen. furt behandelt beide identisch. ## Source-Code beschaffen -### Option 1: Paket-Download (Empfohlen) - -furt wird als versionierte Pakete über den Dragons@Work Package-Server bereitgestellt. Diese Methode ist für Produktions-Installationen empfohlen. - -**Aktuelles Paket herunterladen:** +Du kannst furt entweder als versioniertes Package herunterladen oder direkt aus dem Git-Repository clonen. Packages enthalten bereits alle notwendigen Dateien inklusive Deployment-Templates und Versionshistorie. ```bash -# Paket in temporäres Verzeichnis downloaden -mkdir -p /tmp/furt-install -cd /tmp/furt-install - -# Aktuelle Version herunterladen -curl -OJ https://smida.dragons-at-work.de/api/packages/DAW/generic/furt-api-gateway/0.1.1/furt-api-gateway-v0.1.1.tar.gz - -# Paket extrahieren -tar -xzf furt-api-gateway-v0.1.1.tar.gz -cd furt-api-gateway-v0.1.1 +# Package-Download +curl -OJ https://smida.dragons-at-work.de/api/packages/DAW/generic/furt-api-gateway/0.1.2/furt-api-gateway-v0.1.2.tar.gz +tar -xzf furt-api-gateway-v0.1.2.tar.gz +cd furt-api-gateway-v0.1.2 ``` -**Paket-Integrität prüfen:** +Alternativ kannst du das Git-Repository clonen: ```bash -# merkwerk-Signature validieren (falls verfügbar) -if [ -f .version_history ]; then - echo "Version-History gefunden - merkwerk-Integration aktiv" - cat .version_history | head -3 -fi - -# Grundstruktur validieren -ls -la src/main.lua config/furt.conf.example scripts/start.sh +git clone https://smida.dragons-at-work.de/DAW/furt.git +cd furt ``` -**Warum Paket-Download:** Versionierte Releases ohne Git-Dependencies, definierte Snapshots für reproduzierbare Installationen, merkwerk-Integration bereits vorkonfiguriert. +## Verzeichnisstruktur anlegen -### Option 2: Git-Repository clonen +furt folgt Unix-Konventionen für selbst-installierte Software. Der Source-Code landet in `/usr/local/share/furt/`, die Konfiguration in einem systemspezifischen Config-Verzeichnis. OpenBSD und FreeBSD nutzen `/usr/local/etc/` für selbst-installierte Software um eine klare Trennung zur Basis-Installation zu schaffen. Linux-Distributionen legen alle Konfigurationsdateien in `/etc/`. -Für Development oder wenn neueste Änderungen benötigt werden: +Logs und Runtime-Dateien gehören nach `/var/` - dem traditionellen Verzeichnis für variable Daten. + +## System-Benutzer einrichten + +Aus Sicherheitsgründen läuft furt nicht als Root, sondern als eigener System-Benutzer. OpenBSD verwendet die Konvention `_servicename` für System-Services, während Linux-Distributionen meist den Service-Namen direkt als Benutzer verwenden. ```bash -# Repository clonen -git clone https://smida.dragons-at-work.de/DAW/furt.git /tmp/furt-source -cd /tmp/furt-source +# OpenBSD nutzt _furt als Benutzerkonvention +doas groupadd _furt +doas useradd -g _furt -s /bin/false -d /var/empty _furt ``` -**Repository-Struktur validieren:** -```bash -# Erforderliche Verzeichnisse prüfen -ls -la src/main.lua config/furt.conf.example scripts/start.sh integrations/ - -# Erwartete Struktur: -# src/ - Lua-Quellcode -# config/ - Konfigurationsbeispiele -# scripts/ - Helper-Scripts (start.sh) -# integrations/ - merkwerk-Integration -# docs/ - Dokumentation -# VERSION - Versions-Information -``` - -**Git-Installation falls erforderlich:** - -*OpenBSD:* -```bash -doas pkg_add git -``` - -*Debian/Ubuntu:* -```bash -apt install git -``` -## Systemanforderungen verstehen - -### Lua-Runtime Anforderungen - -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. - -**Erforderliche Lua-Module:** -- `socket` - TCP-Server-Implementation für HTTP-Handling -- `cjson` - JSON-Kodierung für API-Responses ohne externe Parser-Dependencies - -**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. - -### Version-Tracking Integration - -furt integriert `merkwerk` für Selbst-Versionierung und Content-Hashing. Diese Integration ermöglicht eindeutige Versions-Identifikation ohne Git-Dependencies im Produktions-System. - -**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 - -### SMTP-Integration - -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 - -## 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:** +Die Shell `/bin/false` verhindert Login-Versuche auf diesen Account. Das Home-Verzeichnis `/var/empty` ist ein leeres, unveränderliches Verzeichnis. ```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')" +# Linux nutzt furt als System-Benutzer +sudo groupadd --system furt +sudo useradd --system -g furt -s /bin/false -d /var/empty furt ``` -**Warum Command-Detection:** OpenBSD installiert Lua als `lua`, Linux-Distributionen oft als `lua5.1`. +Das `--system` Flag weist niedrige UIDs für System-Services zu und verhindert die Anzeige in Login-Managern. -**Fehlende Module installieren:** +## Verzeichnisse erstellen -*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:** +Jetzt erstellen wir die benötigten Verzeichnisse mit korrekten Berechtigungen: ```bash -# start.sh-Funktionalität testen -cd /usr/local/share/furt -./scripts/start.sh +# OpenBSD Verzeichnisse +doas mkdir -p /usr/local/etc/furt +doas mkdir -p /usr/local/share/furt +doas mkdir -p /var/log/furt +doas mkdir -p /var/run/furt -# Erwartete Ausgabe: -# Auto-detected lua command: lua -# Furt HTTP-Server started on 127.0.0.1:7811 -# [...] +# furt-Benutzer braucht Schreibrechte für Logs und PID-Dateien +doas chown _furt:_furt /var/log/furt +doas chown _furt:_furt /var/run/furt ``` -**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 +Unter Linux ist die Struktur identisch, nur das Config-Verzeichnis liegt direkt in `/etc/`: -### 5. Konfiguration verstehen +```bash +# Linux Verzeichnisse +sudo mkdir -p /etc/furt +sudo mkdir -p /usr/local/share/furt +sudo mkdir -p /var/log/furt +sudo mkdir -p /var/run/furt -furt nutzt INI-Format für menschenlesbare Konfiguration ohne komplexe Parser-Dependencies. +sudo chown furt:furt /var/log/furt +sudo chown furt:furt /var/run/furt +``` -**Konfigurations-Struktur:** -- `[server]` - HTTP-Server-Parameter -- `[smtp_default]` - Standard-SMTP-Einstellungen -- `[api_key "name"]` - Mandanten-spezifische API-Schlüssel +## Source-Code installieren -**Basis-Konfiguration erstellen:** +Der furt-Quellcode wird nach `/usr/local/share/furt/` kopiert. Dieses Verzeichnis enthält den unveränderlichen Code der später von Updates überschrieben werden kann, ohne die maschinenspezifische Konfiguration zu beeinflussen. + +```bash +# Alle Source-Verzeichnisse kopieren +sudo cp -r src/ config/ scripts/ integrations/ /usr/local/share/furt/ + +# Versions-Dateien für merkwerk-Integration falls vorhanden +sudo cp VERSION /usr/local/share/furt/ 2>/dev/null || true +sudo cp .version_history /usr/local/share/furt/ 2>/dev/null || true +``` + +Die Source-Dateien gehören Root und sind nur lesbar. Das `start.sh`-Script benötigt Ausführungsrechte da es als Service-Wrapper fungiert: + +```bash +# OpenBSD nutzt wheel als Admin-Gruppe +sudo chown -R root:wheel /usr/local/share/furt +sudo chmod -R 644 /usr/local/share/furt +sudo find /usr/local/share/furt -type d -exec chmod 755 {} \; +sudo chmod +x /usr/local/share/furt/scripts/start.sh +``` + +Unter Linux ist die Gruppe `root`: + +```bash +# Linux nutzt root als Standard-Gruppe +sudo chown -R root:root /usr/local/share/furt +sudo chmod -R 644 /usr/local/share/furt +sudo find /usr/local/share/furt -type d -exec chmod 755 {} \; +sudo chmod +x /usr/local/share/furt/scripts/start.sh +``` + +## Konfiguration anpassen + +furt nutzt INI-Format für die Konfiguration. Das Beispiel-Config-File enthält bereits eine funktionsfähige Basis-Konfiguration die du an deine Umgebung anpassen musst: + +```bash +# OpenBSD Config-Pfad +doas cp /usr/local/share/furt/config/furt.conf.example /usr/local/etc/furt/furt.conf + +# Linux Config-Pfad +sudo cp /usr/local/share/furt/config/furt.conf.example /etc/furt/furt.conf +``` + +Die wichtigsten Anpassungen betreffen die SMTP-Zugangsdaten und API-Keys. Öffne die Konfigurationsdatei und trage deine SMTP-Server-Details ein: -*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 +host = mail.example.com +user = noreply@example.com +password = your-smtp-password-here ``` -*Linux* - `/etc/furt/furt.conf`: +Der `[api_key]`-Abschnitt definiert welche Websites furt nutzen dürfen und wohin deren Mails weitergeleitet werden: + ```ini -# Identische Konfiguration wie oben +[api_key "website-key"] +name = "Ihre Website" +mail_to = admin@example.com +mail_from = noreply@example.com ``` -**Sicherheits-Berechtigungen für Produktion:** +Da die Konfigurationsdatei SMTP-Passwörter enthält, beschränken wir den Zugriff auf Root und die furt-Gruppe: -*OpenBSD/FreeBSD:* ```bash -chmod 640 /usr/local/etc/furt/furt.conf -chown root:_furt /usr/local/etc/furt/furt.conf +# OpenBSD Berechtigungen +doas chmod 640 /usr/local/etc/furt/furt.conf +doas chown root:_furt /usr/local/etc/furt/furt.conf + +# Linux Berechtigungen +sudo chmod 640 /etc/furt/furt.conf +sudo chown root:furt /etc/furt/furt.conf ``` -*Linux:* -```bash -chmod 640 /etc/furt/furt.conf -chown root:furt /etc/furt/furt.conf -``` +## Service integrieren -**Testing-Berechtigungen:** Für manuelle Tests als normaler Benutzer temporär lesbare Berechtigungen setzen: +furt enthält vorgefertigte Service-Templates für OpenBSD und Linux. Diese Templates sind auf das furt `start.sh`-Script abgestimmt und handhaben PID-Files und User-Switching korrekt. + +Für OpenBSD kopieren wir das rc.d-Script: ```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 +doas cp deployment/openbsd/rc.d-furt /etc/rc.d/furt +doas chmod +x /etc/rc.d/furt echo "furt_flags=" >> /etc/rc.conf.local -rcctl enable furt +doas 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 +Das `furt_flags=` in `/etc/rc.conf.local` ermöglicht es später Command-Line-Parameter zu übergeben. Der `rcctl enable` Befehl aktiviert den automatischen Start beim Booten. + +Unter Linux verwenden wir systemd: -**Linux systemd-Unit aus Repository-Template:** ```bash -# Template aus Repository verwenden -cp deployment/linux/furt.service /etc/systemd/system/ -systemctl daemon-reload -systemctl enable furt +sudo cp deployment/linux/furt.service /etc/systemd/system/ +sudo systemctl daemon-reload +sudo systemctl enable furt ``` -**Das Template `deployment/linux/furt.service` enthält:** -- Service-vs-Interactive-Detection über `start.sh` -- Korrekte User/Group-Konfiguration für Linux -- Restart-Policy für systemd-Integration +Der `daemon-reload` ist notwendig damit systemd die neue Service-Datei erkennt. + +## Service starten und testen + +Jetzt können wir furt starten und die Installation testen: + +```bash +# OpenBSD Service-Start +doas rcctl start furt +doas rcctl check furt +``` + +Der `rcctl check` Befehl zeigt ob der Service läuft. Bei Problemen findest du Fehlerdetails im System-Log. + +```bash +# Linux Service-Start +sudo systemctl start furt +sudo systemctl status furt +``` + +Der `systemctl status` Befehl zeigt detaillierte Service-Informationen inklusive der letzten Log-Ausgaben. ## 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 +Ein erfolgreicher Health-Check bestätigt dass furt läuft und alle Module korrekt geladen sind: ```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 +Die Response zeigt Service-Status, Version und verfügbare Features. Um die Mail-Funktionalität zu testen, sende eine Test-Mail: ```bash curl -X POST http://127.0.0.1:7811/v1/mail/send \ - -H "X-API-Key: daw-frontend-key" \ + -H "X-API-Key: website-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." + "subject": "furt Test", + "message": "Installation erfolgreich" }' ``` -**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. +Eine erfolgreiche Response bestätigt dass SMTP-Konfiguration und API-Key korrekt funktionieren. Die Test-Mail sollte an die in der Konfiguration angegebene Adresse ankommen. \ No newline at end of file