Table of Contents
furt Installation
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.
# 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
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.
# Package-Download
curl -OJ https://smida.dragons-at-work.de/api/packages/DAW/generic/furt-api-gateway/0.1.4/furt-api-gateway-v0.1.4.tar.gz
tar -xzf furt-api-gateway-v0.1.4.tar.gz
cd furt-api-gateway-v0.1.4
Alternativ kannst du das Git-Repository clonen:
git clone https://smida.dragons-at-work.de/DAW/furt.git
cd furt
Verzeichnisstruktur anlegen
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/.
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.
# OpenBSD nutzt _furt als Benutzerkonvention
doas groupadd _furt
doas useradd -g _furt -s /bin/false -d /var/empty _furt
Die Shell /bin/false verhindert Login-Versuche auf diesen Account. Das Home-Verzeichnis /var/empty ist ein leeres, unveränderliches Verzeichnis.
# Linux nutzt furt als System-Benutzer
sudo groupadd --system furt
sudo useradd --system -g furt -s /bin/false -d /var/empty furt
Das --system Flag weist niedrige UIDs für System-Services zu und verhindert die Anzeige in Login-Managern.
Verzeichnisse erstellen
Jetzt erstellen wir die benötigten Verzeichnisse mit korrekten Berechtigungen:
# 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
# furt-Benutzer braucht Schreibrechte für Logs und PID-Dateien
doas chown _furt:_furt /var/log/furt
doas chown _furt:_furt /var/run/furt
Unter Linux ist die Struktur identisch, nur das Config-Verzeichnis liegt direkt in /etc/:
# 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
sudo chown furt:furt /var/log/furt
sudo chown furt:furt /var/run/furt
Source-Code installieren
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.
# 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:
# 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:
# 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:
# 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:
[smtp_default]
host = mail.example.com
user = noreply@example.com
password = your-smtp-password-here
Der [api_key]-Abschnitt definiert welche Websites furt nutzen dürfen und wohin deren Mails weitergeleitet werden:
[api_key "website-key"]
name = "Ihre Website"
mail_to = admin@example.com
mail_from = noreply@example.com
Da die Konfigurationsdatei SMTP-Passwörter enthält, beschränken wir den Zugriff auf Root und die furt-Gruppe:
# 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
Service integrieren
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:
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
doas rcctl enable furt
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:
sudo cp deployment/linux/furt.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable furt
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:
# 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.
# 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
Ein erfolgreicher Health-Check bestätigt dass furt läuft und alle Module korrekt geladen sind:
curl http://127.0.0.1:7811/health
Die Response zeigt Service-Status, Version und verfügbare Features. Um die Mail-Funktionalität zu testen, sende eine Test-Mail:
curl -X POST http://127.0.0.1:7811/v1/mail/send \
-H "X-API-Key: website-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Installation Test",
"email": "test@example.com",
"subject": "furt Test",
"message": "Installation erfolgreich"
}'
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.