DAW/furt
2
0
Fork 0
Code Issues 11 Pull requests Projects Releases 3 Packages 1 Wiki Activity Actions

Home aktualisiert

michael 2025-09-03 13:47:18 +02:00
parent d61a8e2aee
commit d158bad84f
1 changed files with 82 additions and 571 deletions
Download patch file Download diff file Expand all files Collapse all files

653
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.
**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