diff --git a/Home.md b/Home.md index 8c64acb..8ad031f 100644 --- a/Home.md +++ b/Home.md @@ -1,600 +1,111 @@ -# furt Installation Guide +# Furt API Gateway -**Lua API-Gateway für digitale Souveränität** +**Pure Lua HTTP-Server für digitale Souveränität** -## Source-Code beschaffen +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. -### Git-Repository clonen +## Features -furt-Quellen aus dem Dragons@Work-Repository beschaffen: +- **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 +## Quick Start + +### 1. Installation ```bash -# Repository clonen -git clone https://smida.dragons-at-work.de/DAW/furt.git /tmp/furt-source -cd /tmp/furt-source +# 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-Struktur validieren:** +### 2. Basis-Konfiguration ```bash -# Erforderliche Verzeichnisse prüfen -ls -la src/main.lua config/furt.conf.example scripts/start.sh integrations/ +# 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 -# Erwartete Struktur: -# src/ - Lua-Quellcode -# config/ - Konfigurationsbeispiele -# scripts/ - Helper-Scripts (start.sh) -# integrations/ - merkwerk-Integration -# docs/ - Dokumentation -# VERSION - Versions-Information +# 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 ``` -**Git-Installation falls erforderlich:** - -*OpenBSD:* +### 3. Service starten ```bash -doas pkg_add git +# 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) + +# Linux-Systeme: systemd als Standard +# systemd = umfangreich aber einheitlich über Distributionen +sudo systemctl enable furt && sudo systemctl start furt ``` -*Debian/Ubuntu:* +### 4. Testen ```bash -apt install git +curl http://localhost:8080/health ``` -## Systemanforderungen verstehen +## Navigation -### Lua-Runtime Anforderungen +### Installation & Setup +- **[Installation](Installation.md)** - Vollständige Installationsanleitung +- **[Konfiguration](Configuration.md)** - Config-System Dokumentation +- **[Troubleshooting](Troubleshooting.md)** - Häufige Probleme -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. +### Development +- **[Development Setup](Development.md)** - Lokale Entwicklungsumgebung +- **[API Documentation](API-Documentation.md)** - Endpunkte und Verwendung +- **[Contributing](Contributing.md)** - Beitrag zum Projekt -**Erforderliche Lua-Module:** -- `socket` - TCP-Server-Implementation für HTTP-Handling -- `cjson` - JSON-Kodierung für API-Responses ohne externe Parser-Dependencies +### Current Status -**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. +**v1.0.0 Features:** +- ✅ Mail-Service (`POST /v1/mail/send`) +- ✅ Health-Check (`GET /health`) +- ✅ API-Key Authentication +- ✅ Multi-Tenant Configuration +- ✅ Rate Limiting +- ✅ CORS Support -### Version-Tracking Integration +**Roadmap:** +- 🔄 Comment-Service (sagjan integration) +- 📋 Project-Management-Service (lengan) +- 💳 Payment-Service (wixlaz) -furt integriert `merkwerk` für Selbst-Versionierung und Content-Hashing. Diese Integration ermöglicht eindeutige Versions-Identifikation ohne Git-Dependencies im Produktions-System. +## Architecture -**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 +Furt folgt dem **Service-Separation-Prinzip**: +- **furt** = Service-Discovery-Coordinator +- **sagjan** = Comments (separate namespace) +- **formular2mail** = Mail-Routing (separate namespace) -### SMTP-Integration +Jeder Service behält seine eigene Konfiguration, furt koordiniert nur die Discovery und das Routing. -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. +**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 -**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:** - -```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. \ No newline at end of file +**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