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

Installation aktualisiert

michael 2025-09-01 17:50:28 +02:00
parent 0a18fc5db8
commit a137a52fd4
1 changed files with 434 additions and 332 deletions
Download patch file Download diff file Expand all files Collapse all files

766
Installation.md

@ -1,442 +1,544 @@
# Installation
# furt Installation Guide
## 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
**Lua API-Gateway für digitale Souveränität**
## Systemanforderungen verstehen
### Lua 5.1 Requirement
### Lua-Runtime Anforderungen
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.
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.
### Warum ein eigener Benutzer
**Erforderliche Lua-Module:**
- `socket` - TCP-Server-Implementation für HTTP-Handling
- `cjson` - JSON-Kodierung für API-Responses ohne externe Parser-Dependencies
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
**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.
Der Unterstrich-Prefix markiert System-Benutzer (Konvention).
### Version-Tracking Integration
### Warum diese Verzeichnis-Struktur
furt integriert `merkwerk` für Selbst-Versionierung und Content-Hashing. Diese Integration ermöglicht eindeutige Versions-Identifikation ohne Git-Dependencies im Produktions-System.
**Konfigurations-Verzeichnis:**
- BSD: `/usr/local/etc/furt/` (Package-Namensraum)
- Linux: `/etc/furt/` (Einheitlicher Namensraum)
**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
**Log-Verzeichnis:** `/var/log/furt/`
- Standard-Pfad für System-Logs
### SMTP-Integration
**Anwendungs-Verzeichnis:** `/usr/local/share/furt/`
- Schreibgeschützte Programm-Dateien
- Getrennt von Konfiguration und Protokollen
- Standard-Location für Architektur-unabhängige Daten
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.
### Berechtigungs-Modell
**SMTP-Requirements:**
- Funktionierender SMTP-Server (intern oder extern)
- SMTP-Authentifizierung (USERNAME/PASSWORD)
- SSL/TLS-Unterstützung für sichere Verbindungen
**Konfigurations-Dateien:** 644 root:root (644 root:wheel auf BSD)
- Lesbar für Dienst, nicht änderbar
- System-Administrator kann Konfiguration bearbeiten
## Installation verstehen
**Vertrauliche Daten:** 600 root:root
- Nur Root-Lesezugriff
- API-Keys und SMTP-Passwörter isoliert
### Verzeichnis-Layout nach POSIX-Standards
**Protokolle:** 755 _furt:_furt
- Dienst kann eigene Protokolle schreiben
- Andere Benutzer können Protokolle lesen (für Debugging)
furt folgt etablierten Unix-Konventionen für selbst-installierte Software:
## 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:**
**OpenBSD/FreeBSD-Layout:**
```
/usr/local/etc/furt/furt.conf # Package-Konfigurations-Namensraum
/usr/local/share/furt/ # Anwendungs-Dateien
/var/log/furt/ # Standard Log-Location
/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-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:**
**Linux-Layout:**
```
/etc/furt/furt.conf # Einheitlicher Konfigurations-Namensraum
/usr/local/share/furt/ # Anwendungs-Dateien
/var/log/furt/ # Standard Log-Location
/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
```
**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/)
**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.
## Manuelle Installation Schritt für Schritt
### Lua-Pfad-Mechanismus
### 1. Abhängigkeiten installieren
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:**
```bash
# OpenBSD (lua 5.1 ist Standard)
pkg_add lua lua-socket lua-cjson
# Lua 5.1 verfügbar?
lua5.1 -v
# FreeBSD
pkg install lua51 lua51-luasocket lua51-lua-cjson
# Erwartete Ausgabe:
# Lua 5.1.5 Copyright (C) 1994-2012 Lua.org, PUC-Rio
# Debian/Ubuntu
apt install lua5.1 lua-socket lua-cjson
# Arch
pacman -S lua51 lua51-socket lua51-cjson
# Required modules testen
lua5.1 -e "require('socket')"
lua5.1 -e "require('cjson')"
```
### 2. Dienst-Benutzer erstellen
**Fehlende Module installieren:**
*OpenBSD:*
```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
pkg_add lua-socket lua-cjson
```
**Warum diese Parameter:**
- `-s /bin/false`: Kein Shell-Login möglich
- `-d /nonexistent`: Kein Home-Verzeichnis
- `-r`: System-Account (Linux)
### 3. Verzeichnis-Struktur erstellen
*Debian/Ubuntu:*
```bash
# BSD-Systeme
mkdir -p /usr/local/etc/furt/secrets
mkdir -p /usr/local/share/furt
mkdir -p /var/log/furt
apt install lua-socket lua-cjson
```
# Linux-Systeme
mkdir -p /etc/furt/secrets
*Arch Linux:*
```bash
pacman -S lua51-socket lua51-cjson
```
### 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
```
### 4. Berechtigungen setzen
*Linux:*
```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
mkdir -p /etc/furt
mkdir -p /usr/local/share/furt
mkdir -p /var/log/furt
chown furt:furt /var/log/furt
```
### 5. Anwendungs-Dateien kopieren
### 3. furt-Quellen installieren
**Source-Code kopieren:**
```bash
# Quell-Dateien ins Anwendungs-Verzeichnis
# Haupt-Bibliothek installieren
cp -r src/ /usr/local/share/furt/
cp -r config/ /usr/local/share/furt/
cp -r integrations/ /usr/local/share/furt/
# Lua-Dateien ausführbar machen
chmod +x /usr/local/share/furt/src/main.lua
# 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 {} \;
```
### 6. Konfiguration erstellen
### 4. Startup-Script erstellen
**Wrapper-Script für Lua-Pfad-Management:**
*OpenBSD/FreeBSD* - `/usr/local/bin/furt`:
```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
# furt HTTP API-Gateway
chmod +x /usr/local/etc/rc.d/furt
# Lua-Module-Pfad für furt erweitern
export LUA_PATH="/usr/local/share/furt/?.lua;;"
# Working Directory für relative Pfade
cd /usr/local/share/furt
# Lua-Interpreter mit main.lua starten
exec lua5.1 src/main.lua "$@"
```
#### Linux (systemd)
*Linux* - `/usr/local/bin/furt`:
```bash
# Dienst-Unit erstellen
cat > /etc/systemd/system/furt.service << 'EOF'
#!/bin/bash
# furt HTTP API-Gateway
# Lua-Module-Pfad für furt erweitern
export LUA_PATH="/usr/local/share/furt/?.lua;;"
# Working Directory für relative Pfade
cd /usr/local/share/furt
# Lua-Interpreter mit main.lua starten
exec lua5.1 src/main.lua "$@"
```
```bash
chmod +x /usr/local/bin/furt
```
**Warum ein Wrapper-Script:** Lua benötigt explizite Pfad-Konfiguration für Module-Erkennung. Das Script setzt `LUA_PATH` ohne globale Environment-Änderungen.
### 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:**
*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
```
### 6. Service-Integration
**OpenBSD rc.d-Script** - `/etc/rc.d/furt`:
```bash
#!/bin/ksh
daemon="/usr/local/bin/furt"
daemon_flags=""
daemon_user="_furt"
daemon_logger="daemon.info"
. /etc/rc.d/rc.subr
rc_cmd $1
```
```bash
chmod +x /etc/rc.d/furt
echo "furt_flags=" >> /etc/rc.conf.local
rcctl enable furt
```
**Linux systemd-Unit** - `/etc/systemd/system/furt.service`:
```ini
[Unit]
Description=Furt API Gateway
Description=furt Multi-Tenant 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
User=furt
Group=furt
ExecStart=/usr/local/bin/furt
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
WorkingDirectory=/usr/local/share/furt
[Install]
WantedBy=multi-user.target
EOF
```
```bash
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
```
## Installation validieren
### Service starten und Status prüfen
**OpenBSD:**
```bash
rcctl start furt
rcctl check furt
```
**Linux:**
```bash
systemctl start furt
systemctl status furt
```
### 9. Funktionstest
### Health-Check durchführen
```bash
# Dienst-Status
# OpenBSD: rcctl check furt
# FreeBSD: service furt status
# Linux: systemctl status furt
# HTTP-Endpunkt
curl http://localhost:7811/health
curl http://127.0.0.1:7811/health
```
Erwartete Antwort:
**Erwartete Response:**
```json
{"status":"healthy","service":"furt-lua","version":"1.0.0"}
{
"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
}
}
```
## Hilfsskripte (Optional)
**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
Diese manuellen Schritte lassen sich durch modulare Hilfsskripte automatisieren:
### Mail-Funktionalität testen
- **`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
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."
}'
```
**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
**Erfolgreiche Response:**
```json
{
"success": true,
"message": "Mail sent successfully",
"tenant": {
"name": "Dragons@Work Website",
"recipient": "admin@dragons-at-work.de"
}
}
```
**Typische Fehlermeldungen:**
## Multi-Mandanten-Konfiguration
*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
### Zusätzliche Websites hinzufügen
*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
furt unterstützt mehrere Websites über separate API-Schlüssel mit mandanten-spezifischer Konfiguration.
*Ungültige SMTP-Konfiguration:*
```
Warning: No default SMTP configured, using localhost:25
```
→ `[smtp_default]` Sektion vervollständigen
**Neue Website-Konfiguration hinzufügen:**
### Prozess läuft nicht
```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] "
```
**Diagnose-Kommandos:**
**Service neu starten für Konfiguration-Reload:**
*OpenBSD:*
```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
rcctl restart furt
```
**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:
*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
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/
ss -tlnp | grep 7811
lsof -i:7811
```
### HTTP-Endpunkt nicht erreichbar
**Lösung:** Port in `furt.conf` ändern und Service neu starten.
**Verbindungstest:**
### Lua-Module nicht gefunden
**Symptom:**
```bash
# Lokaler Test
curl -v http://localhost:7811/health
# Netzwerk-Test (von anderem Rechner)
curl -v http://SERVER_IP:7811/health
$ furt
lua5.1: src/main.lua:4: module 'socket' not found
```
**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:**
**Diagnose und Lösung:**
```bash
# OpenBSD: /etc/pf.conf erweitern
pass in on egress proto tcp to port 7811
# Module-Verfügbarkeit prüfen
lua5.1 -e "print(package.path)"
lua5.1 -e "require('socket')"
# Linux: iptables oder ufw
ufw allow 7811
```
# 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.