From 8b7806670cf46128e8553b7efde353896b24aa48 Mon Sep 17 00:00:00 2001 From: michael Date: Wed, 10 Sep 2025 12:20:41 +0200 Subject: [PATCH 1/2] docs: simplify README and remove FreeBSD support - Strip README to essentials with wiki references only - Remove non-existent API docs and troubleshooting links - Focus on quick start and actual integrations (merkwerk) - Remove FreeBSD support from all installation scripts - Clean up platform detection logic in scripts - Maintain OpenBSD and Linux support only Reduces maintenance burden and aligns with actual project scope. --- README.md | 159 ++++++++----------------------- docs/setup-guide.md | 176 ----------------------------------- install.sh | 2 +- scripts/create-service.sh | 8 +- scripts/setup-directories.sh | 2 +- scripts/setup-user.sh | 2 +- scripts/start.sh | 2 +- scripts/sync-files.sh | 9 +- scripts/validate-config.sh | 2 +- src/config_parser.lua | 2 +- 10 files changed, 58 insertions(+), 306 deletions(-) delete mode 100644 docs/setup-guide.md diff --git a/README.md b/README.md index d27042b..a18d120 100644 --- a/README.md +++ b/README.md @@ -1,160 +1,83 @@ # Furt API Gateway -**HTTP-Server in Lua für Service-Integration** +**Pure Lua HTTP-Server für digitale Souveränität** ## Überblick -Furt ist ein HTTP-Server der verschiedene Services unter einer API vereint. Aktuell unterstützt es Mail-Versendung über SMTP und bietet eine einfache JSON-API für Web-Integration. +Furt ist ein minimalistisches HTTP-Server in Lua 5.1 für Mail-Versendung über SMTP. Es bietet eine einfache JSON-API für Web-Integration und Multi-Tenant-Unterstützung über API-Keys. ## Features - HTTP-Server mit JSON-APIs -- Mail-Versendung über SMTP -- Request-Routing und Authentication +- Multi-Tenant Mail-Routing über SMTP +- API-Key-basierte Authentifizierung - Health-Check-Endpoints -- Konfigurierbare Rate-Limiting -- Hugo/Website-Integration +- Rate-Limiting pro API-Key +- CORS-Support für Frontend-Integration -## Dependencies +## Quick Start -**Erforderlich:** -- `lua` 5.4+ -- `lua-socket` (HTTP-Server) -- `lua-cjson` (JSON-Verarbeitung) +**Dependencies installieren:** +```bash +# OpenBSD +doas pkg_add lua lua-socket lua-cjson luasec + +# Debian/Ubuntu +sudo apt install lua5.1 lua-socket lua-cjson lua-sec + +# Arch Linux +sudo pacman -S lua51 lua51-socket lua51-dkjson lua51-sec +``` **Installation:** ```bash -# Arch Linux -pacman -S lua lua-socket lua-cjson - -# Ubuntu/Debian -apt install lua5.4 lua-socket lua-cjson -``` - -## Installation - -```bash -# Repository klonen -git clone +git clone https://smida.dragons-at-work.de/DAW/furt.git cd furt - -# Scripts ausführbar machen -chmod +x scripts/*.sh - -# Server starten -./scripts/start.sh +sudo ./install.sh ``` -**Server läuft auf:** http://127.0.0.1:8080 +**Server läuft auf:** http://127.0.0.1:7811 ## API-Endpoints -### Health Check +**Health Check:** ```bash -GET /health -→ {"status":"healthy","service":"furt","version":"1.0.0"} +curl http://127.0.0.1:7811/health ``` -### Mail senden +**Mail senden:** ```bash -POST /v1/mail/send -Content-Type: application/json - -{ - "name": "Name", - "email": "sender@example.com", - "message": "Nachricht" -} - -→ {"success":true,"message":"Mail sent"} -``` - -## Konfiguration - -**Environment Variables (.env):** -```bash -FURT_MAIL_HOST=mail.example.com -FURT_MAIL_PORT=587 -FURT_MAIL_USERNAME=user@example.com -FURT_MAIL_PASSWORD=password -FURT_MAIL_TO=empfaenger@example.com -``` - -**Server-Config (config/server.lua):** -- Port und Host-Einstellungen -- API-Key-Konfiguration -- Rate-Limiting-Parameter - -## Testing - -**Automatische Tests:** -```bash -lua tests/test_http.lua -``` - -**Manuelle Tests:** -```bash -./scripts/test_curl.sh - -# Oder direkt: -curl -X POST http://127.0.0.1:8080/v1/mail/send \ +curl -X POST http://127.0.0.1:7811/v1/mail/send \ + -H "X-API-Key: your-api-key" \ -H "Content-Type: application/json" \ - -d '{"name":"Test","email":"test@example.com","message":"Test"}' + -d '{"name":"Test","email":"test@example.com","subject":"Test","message":"Test-Nachricht"}' ``` -## Deployment +## Dokumentation -**OpenBSD:** -- rc.d-Script in `deployment/openbsd/` -- Systemd-Integration über Scripts - -**Production-Setup:** -```bash -# Environment-Config kopieren -cp .env.example .env.production -# → SMTP-Credentials anpassen - -# Production-Mode starten -export FURT_ENV=production -./scripts/start.sh -``` +**Installation & Konfiguration:** [Furt Wiki](https://smida.dragons-at-work.de/DAW/furt/wiki) ## Projektstruktur ``` furt/ ├── src/ # Lua-Source-Code -│ ├── main.lua # HTTP-Server -│ ├── routes/ # API-Endpoints -│ └── smtp.lua # Mail-Integration -├── config/ # Konfiguration -├── scripts/ # Start/Test-Scripts -├── tests/ # Test-Suite -└── deployment/ # System-Integration +├── config/ # Konfiguration +├── scripts/ # Installation & Management +└── deployment/ # System-Integration ``` -## Hugo-Integration +## Integration -**Shortcode-Beispiel:** -```html -
- - - - -
-``` +**merkwerk:** Versionierte Furt-Deployment über [merkwerk](https://smida.dragons-at-work.de/DAW/merkwerk) -## Development +## License -**Code-Struktur:** -- Module unter 200 Zeilen -- Funktionen unter 50 Zeilen -- Klare Fehlerbehandlung -- Testbare Komponenten +ISC - Siehe [LICENSE](LICENSE) für Details. -**Dependencies minimal halten:** -- Nur lua-socket und lua-cjson -- Keine externen HTTP-Libraries -- Standard-Lua-Funktionen bevorzugen +## Links + +- **Repository:** [Forgejo](https://smida.dragons-at-work.de/DAW/furt) +- **Dokumentation:** [Wiki](https://smida.dragons-at-work.de/DAW/furt/wiki) +- **Projekt:** [Dragons@Work](https://dragons-at-work.de) diff --git a/docs/setup-guide.md b/docs/setup-guide.md deleted file mode 100644 index 2dc790e..0000000 --- a/docs/setup-guide.md +++ /dev/null @@ -1,176 +0,0 @@ -# Multi-Tenant furt Setup-Anleitung - -## Installation - -### 1. Dateien platzieren - -```bash -# OpenBSD/FreeBSD -mkdir -p /usr/local/etc/furt -mkdir -p /usr/local/share/furt - -# Oder Linux -mkdir -p /etc/furt -mkdir -p /usr/local/share/furt - -# Source code -cp -r src/ /usr/local/share/furt/ -cp -r config/ /usr/local/share/furt/ -``` - -### 2. Konfiguration erstellen - -```bash -# Beispiel-Config kopieren und anpassen -# OpenBSD/FreeBSD: -cp furt.conf.example /usr/local/etc/furt/furt.conf - -# Linux: -cp furt.conf.example /etc/furt/furt.conf - -# Config editieren -vi /usr/local/etc/furt/furt.conf # oder /etc/furt/furt.conf -``` - -### 3. Start-Script - -```bash -#!/bin/sh -# /usr/local/bin/furt - -cd /usr/local/share/furt -lua src/main.lua -``` - -## Multi-Tenant Konfiguration - -### Beispiel für 3 Websites - -```ini -[server] -host = 127.0.0.1 -port = 8080 - -[smtp_default] -host = mail.dragons-at-work.de -port = 465 -user = noreply@dragons-at-work.de -password = your-smtp-password - -# Website 1: Dragons@Work -[api_key "daw-key-abc123"] -name = "Dragons@Work Website" -permissions = mail:send -allowed_ips = 1.2.3.4/32, 10.0.0.0/8 -mail_to = admin@dragons-at-work.de -mail_from = noreply@dragons-at-work.de -mail_subject_prefix = "[DAW] " - -# Website 2: Biocodie (gleiche SMTP, andere Empfänger) -[api_key "bio-key-def456"] -name = "Biocodie Website" -permissions = mail:send -allowed_ips = 5.6.7.8/32 -mail_to = contact@biocodie.de -mail_from = noreply@biocodie.de -mail_subject_prefix = "[Biocodie] " - -# Website 3: Kunde mit eigenem SMTP -[api_key "kunde-key-ghi789"] -name = "Kunde X Website" -permissions = mail:send -allowed_ips = 9.10.11.12/32 -mail_to = info@kunde-x.de -mail_from = noreply@kunde-x.de -mail_smtp_host = mail.kunde-x.de -mail_smtp_user = noreply@kunde-x.de -mail_smtp_pass = kunde-smtp-password -``` - -## Admin-Workflow - -### Neue Website hinzufügen - -1. **Config editieren:** -```bash -vi /usr/local/etc/furt/furt.conf -``` - -2. **Neuen API-Key-Block hinzufügen:** -```ini -[api_key "neue-website-key"] -name = "Neue Website" -permissions = mail:send -allowed_ips = 12.34.56.78/32 -mail_to = contact@neue-website.de -mail_from = noreply@neue-website.de -``` - -3. **furt neu starten:** -```bash -systemctl restart furt -# oder -pkill -f "lua.*main.lua" && /usr/local/bin/furt & -``` - -### Website testen - -```bash -# Test mit curl -curl -X POST http://localhost:8080/v1/mail/send \ - -H "X-API-Key: neue-website-key" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Test User", - "email": "test@example.com", - "subject": "Test Message", - "message": "This is a test message" - }' -``` - -## Vorteile des Multi-Tenant-Systems - -### ✅ Ein Server, viele Websites -- Alle Websites nutzen eine furt-Instanz -- Jede Website hat eigenen API-Key -- Verschiedene Empfänger-Adressen -- Verschiedene SMTP-Server möglich - -### ✅ Admin-freundlich -- Nginx-style Config-Format -- Einfach neue Websites hinzufügen -- Klare Struktur pro Website -- Kommentare möglich - -### ✅ Sicher -- IP-Restrictions pro Website -- Permissions pro API-Key -- Separate SMTP-Credentials möglich -- Rate-Limiting bleibt erhalten - -### ✅ Flexibel -- Default SMTP + website-spezifische SMTP -- Subject-Prefix pro Website -- Verschiedene Mail-Adressen -- Beliebig viele Websites - -## Backward Compatibility - -Das neue System ist **vollständig kompatibel** mit der alten config/server.lua API. Bestehende Module (auth.lua, main.lua, etc.) funktionieren ohne Änderungen. - -## Troubleshooting - -### Config-Parsing-Fehler -```bash -# Config-Syntax prüfen -lua -e "require('src.config_parser').parse_file('/usr/local/etc/furt/furt.conf')" -``` - -### Mail-Routing testen -```bash -# Logs anschauen -tail -f /var/log/furt.log - -# Debug-Mode -FURT_DEBUG=true lua src/main.lua -``` \ No newline at end of file diff --git a/install.sh b/install.sh index 9de2751..4711c2b 100755 --- a/install.sh +++ b/install.sh @@ -102,7 +102,7 @@ else echo "" echo "Next steps:" echo "1. Edit configuration file:" - if [ "$(uname)" = "OpenBSD" ] || [ "$(uname)" = "FreeBSD" ]; then + if [ "$(uname)" = "OpenBSD" ]; then echo " /usr/local/etc/furt/furt.conf" else echo " /etc/furt/furt.conf" diff --git a/scripts/create-service.sh b/scripts/create-service.sh index 9732479..eed3ebe 100755 --- a/scripts/create-service.sh +++ b/scripts/create-service.sh @@ -15,25 +15,25 @@ if [ "$(uname)" = "OpenBSD" ]; then echo "Error: deployment/openbsd/rc.d-furt template not found" exit 1 fi - + 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 echo "OpenBSD service created and enabled using repository template" - + elif [ "$(uname)" = "Linux" ]; then # Use systemd template from repository if [ ! -f "deployment/linux/furt.service" ]; then echo "Error: deployment/linux/furt.service template not found" exit 1 fi - + cp deployment/linux/furt.service /etc/systemd/system/ systemctl daemon-reload systemctl enable furt echo "Linux systemd service created and enabled using repository template" - + else echo "Unsupported operating system for service creation" exit 1 diff --git a/scripts/setup-directories.sh b/scripts/setup-directories.sh index 97cc02f..63881c3 100755 --- a/scripts/setup-directories.sh +++ b/scripts/setup-directories.sh @@ -4,7 +4,7 @@ set -e # Detect operating system for config directory -if [ "$(uname)" = "OpenBSD" ] || [ "$(uname)" = "FreeBSD" ]; then +if [ "$(uname)" = "OpenBSD" ]; then CONFIG_DIR="/usr/local/etc/furt" USER="_furt" GROUP="_furt" diff --git a/scripts/setup-user.sh b/scripts/setup-user.sh index 29cdb61..9188626 100755 --- a/scripts/setup-user.sh +++ b/scripts/setup-user.sh @@ -4,7 +4,7 @@ set -e # Detect operating system -if [ "$(uname)" = "OpenBSD" ] || [ "$(uname)" = "FreeBSD" ]; then +if [ "$(uname)" = "OpenBSD" ]; then # BSD systems use _furt user convention groupadd _furt 2>/dev/null || true useradd -g _furt -s /bin/false -d /var/empty _furt 2>/dev/null || true diff --git a/scripts/start.sh b/scripts/start.sh index 41db621..1aadf21 100755 --- a/scripts/start.sh +++ b/scripts/start.sh @@ -17,7 +17,7 @@ echo -e "${GREEN}=== Furt Lua HTTP-Server Startup ===${NC}" LUA_COMMAND="" # Config check first -if [ "$(uname)" = "OpenBSD" ] || [ "$(uname)" = "FreeBSD" ]; then +if [ "$(uname)" = "OpenBSD" ]; then CONFIG_FILE="/usr/local/etc/furt/furt.conf" PID_FILE="/var/run/furt/furt.pid" else diff --git a/scripts/sync-files.sh b/scripts/sync-files.sh index b495a78..34d3957 100755 --- a/scripts/sync-files.sh +++ b/scripts/sync-files.sh @@ -24,8 +24,13 @@ cp -r integrations/ "$TARGET/" [ -f "VERSION" ] && cp VERSION "$TARGET/" [ -f ".version_history" ] && cp .version_history "$TARGET/" -# Set proper permissions -chown -R root:wheel "$TARGET" 2>/dev/null || chown -R root:root "$TARGET" +# Set proper permissions based on operating system +if [ "$(uname)" = "OpenBSD" ]; then + chown -R root:wheel "$TARGET" +else + chown -R root:root "$TARGET" +fi + chmod -R 644 "$TARGET" find "$TARGET" -type d -exec chmod 755 {} \; chmod +x "$TARGET/scripts/start.sh" diff --git a/scripts/validate-config.sh b/scripts/validate-config.sh index ff55f1a..220cf69 100755 --- a/scripts/validate-config.sh +++ b/scripts/validate-config.sh @@ -4,7 +4,7 @@ set -e # Detect config file location -if [ "$(uname)" = "OpenBSD" ] || [ "$(uname)" = "FreeBSD" ]; then +if [ "$(uname)" = "OpenBSD" ]; then CONFIG_FILE="/usr/local/etc/furt/furt.conf" else CONFIG_FILE="/etc/furt/furt.conf" diff --git a/src/config_parser.lua b/src/config_parser.lua index 6fa36d5..8760014 100644 --- a/src/config_parser.lua +++ b/src/config_parser.lua @@ -215,7 +215,7 @@ end function ConfigParser.load_config() -- Try different locations based on OS local config_paths = { - "/usr/local/etc/furt/furt.conf", -- OpenBSD/FreeBSD + "/usr/local/etc/furt/furt.conf", -- OpenBSD "/etc/furt/furt.conf", -- Linux "config/furt.conf", -- Development "furt.conf" -- Current directory From 166325b13389de593c9af77cd77510e0f573d3f8 Mon Sep 17 00:00:00 2001 From: michael Date: Wed, 10 Sep 2025 12:20:41 +0200 Subject: [PATCH 2/2] chore: merkwerk auto-update --- .version_history | 1 + 1 file changed, 1 insertion(+) diff --git a/.version_history b/.version_history index 9667056..54e76dd 100644 --- a/.version_history +++ b/.version_history @@ -25,3 +25,4 @@ a670de0f,59f372f,feature/pid-file-service-management,2025-09-07T14:58:01Z,michae a670de0f,683d6e5,fix/validate-config-posix-regex,2025-09-07T16:00:48Z,michael,git,lua-api a670de0f,24bd94d,feature/systemd-hardening,2025-09-07T16:40:47Z,michael,git,lua-api 4ee95dbc,08b49d3,security/sanitize-test-scripts,2025-09-07T19:25:38Z,michael,git,lua-api +59c85431,8b78066,main,2025-09-10T10:20:50Z,michael,git,lua-api