Installation aktualisiert
parent
11d572a2fd
commit
fcc9e2154a
1 changed files with 171 additions and 547 deletions
718
Installation.md
718
Installation.md
|
|
@ -1,620 +1,244 @@
|
||||||
# furt Installation Guide
|
# furt Installation
|
||||||
|
|
||||||
**Lua API-Gateway für digitale Souveränität**
|
**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.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
## Source-Code beschaffen
|
||||||
|
|
||||||
### Option 1: Paket-Download (Empfohlen)
|
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.
|
||||||
|
|
||||||
furt wird als versionierte Pakete über den Dragons@Work Package-Server bereitgestellt. Diese Methode ist für Produktions-Installationen empfohlen.
|
|
||||||
|
|
||||||
**Aktuelles Paket herunterladen:**
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Paket in temporäres Verzeichnis downloaden
|
# Package-Download
|
||||||
mkdir -p /tmp/furt-install
|
curl -OJ https://smida.dragons-at-work.de/api/packages/DAW/generic/furt-api-gateway/0.1.2/furt-api-gateway-v0.1.2.tar.gz
|
||||||
cd /tmp/furt-install
|
tar -xzf furt-api-gateway-v0.1.2.tar.gz
|
||||||
|
cd furt-api-gateway-v0.1.2
|
||||||
# Aktuelle Version herunterladen
|
|
||||||
curl -OJ https://smida.dragons-at-work.de/api/packages/DAW/generic/furt-api-gateway/0.1.1/furt-api-gateway-v0.1.1.tar.gz
|
|
||||||
|
|
||||||
# Paket extrahieren
|
|
||||||
tar -xzf furt-api-gateway-v0.1.1.tar.gz
|
|
||||||
cd furt-api-gateway-v0.1.1
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Paket-Integrität prüfen:**
|
Alternativ kannst du das Git-Repository clonen:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# merkwerk-Signature validieren (falls verfügbar)
|
git clone https://smida.dragons-at-work.de/DAW/furt.git
|
||||||
if [ -f .version_history ]; then
|
cd furt
|
||||||
echo "Version-History gefunden - merkwerk-Integration aktiv"
|
|
||||||
cat .version_history | head -3
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Grundstruktur validieren
|
|
||||||
ls -la src/main.lua config/furt.conf.example scripts/start.sh
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Warum Paket-Download:** Versionierte Releases ohne Git-Dependencies, definierte Snapshots für reproduzierbare Installationen, merkwerk-Integration bereits vorkonfiguriert.
|
## Verzeichnisstruktur anlegen
|
||||||
|
|
||||||
### Option 2: Git-Repository clonen
|
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/`.
|
||||||
|
|
||||||
Für Development oder wenn neueste Änderungen benötigt werden:
|
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.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Repository clonen
|
# OpenBSD nutzt _furt als Benutzerkonvention
|
||||||
git clone https://smida.dragons-at-work.de/DAW/furt.git /tmp/furt-source
|
doas groupadd _furt
|
||||||
cd /tmp/furt-source
|
doas useradd -g _furt -s /bin/false -d /var/empty _furt
|
||||||
```
|
```
|
||||||
|
|
||||||
**Repository-Struktur validieren:**
|
Die Shell `/bin/false` verhindert Login-Versuche auf diesen Account. Das Home-Verzeichnis `/var/empty` ist ein leeres, unveränderliches Verzeichnis.
|
||||||
```bash
|
|
||||||
# Erforderliche Verzeichnisse prüfen
|
|
||||||
ls -la src/main.lua config/furt.conf.example scripts/start.sh integrations/
|
|
||||||
|
|
||||||
# Erwartete Struktur:
|
|
||||||
# src/ - Lua-Quellcode
|
|
||||||
# config/ - Konfigurationsbeispiele
|
|
||||||
# scripts/ - Helper-Scripts (start.sh)
|
|
||||||
# integrations/ - merkwerk-Integration
|
|
||||||
# docs/ - Dokumentation
|
|
||||||
# VERSION - Versions-Information
|
|
||||||
```
|
|
||||||
|
|
||||||
**Git-Installation falls erforderlich:**
|
|
||||||
|
|
||||||
*OpenBSD:*
|
|
||||||
```bash
|
|
||||||
doas pkg_add git
|
|
||||||
```
|
|
||||||
|
|
||||||
*Debian/Ubuntu:*
|
|
||||||
```bash
|
|
||||||
apt install git
|
|
||||||
```
|
|
||||||
## Systemanforderungen verstehen
|
|
||||||
|
|
||||||
### Lua-Runtime Anforderungen
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
**Erforderliche Lua-Module:**
|
|
||||||
- `socket` - TCP-Server-Implementation für HTTP-Handling
|
|
||||||
- `cjson` - JSON-Kodierung für API-Responses ohne externe Parser-Dependencies
|
|
||||||
|
|
||||||
**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.
|
|
||||||
|
|
||||||
### Version-Tracking Integration
|
|
||||||
|
|
||||||
furt integriert `merkwerk` für Selbst-Versionierung und Content-Hashing. Diese Integration ermöglicht eindeutige Versions-Identifikation ohne Git-Dependencies im Produktions-System.
|
|
||||||
|
|
||||||
**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
|
|
||||||
|
|
||||||
### SMTP-Integration
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
**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
|
```bash
|
||||||
# Lua-Command erkennen (plattformspezifisch)
|
# Linux nutzt furt als System-Benutzer
|
||||||
if command -v lua5.1 >/dev/null 2>&1; then
|
sudo groupadd --system furt
|
||||||
LUA_CMD="lua5.1"
|
sudo useradd --system -g furt -s /bin/false -d /var/empty furt
|
||||||
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`.
|
Das `--system` Flag weist niedrige UIDs für System-Services zu und verhindert die Anzeige in Login-Managern.
|
||||||
|
|
||||||
**Fehlende Module installieren:**
|
## Verzeichnisse erstellen
|
||||||
|
|
||||||
*Arch Linux:*
|
Jetzt erstellen wir die benötigten Verzeichnisse mit korrekten Berechtigungen:
|
||||||
```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
|
```bash
|
||||||
# start.sh-Funktionalität testen
|
# OpenBSD Verzeichnisse
|
||||||
cd /usr/local/share/furt
|
doas mkdir -p /usr/local/etc/furt
|
||||||
./scripts/start.sh
|
doas mkdir -p /usr/local/share/furt
|
||||||
|
doas mkdir -p /var/log/furt
|
||||||
|
doas mkdir -p /var/run/furt
|
||||||
|
|
||||||
# Erwartete Ausgabe:
|
# furt-Benutzer braucht Schreibrechte für Logs und PID-Dateien
|
||||||
# Auto-detected lua command: lua
|
doas chown _furt:_furt /var/log/furt
|
||||||
# Furt HTTP-Server started on 127.0.0.1:7811
|
doas chown _furt:_furt /var/run/furt
|
||||||
# [...]
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Warum start.sh statt direkter Lua-Aufruf:**
|
Unter Linux ist die Struktur identisch, nur das Config-Verzeichnis liegt direkt in `/etc/`:
|
||||||
- Automatische Lua-Command-Detection (lua vs lua5.1)
|
|
||||||
- Service-vs-Interactive-Mode-Erkennung
|
|
||||||
- Plattformspezifische Pfad-Anpassungen
|
|
||||||
- Robuste Daemon-Integration
|
|
||||||
|
|
||||||
### 5. Konfiguration verstehen
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
furt nutzt INI-Format für menschenlesbare Konfiguration ohne komplexe Parser-Dependencies.
|
sudo chown furt:furt /var/log/furt
|
||||||
|
sudo chown furt:furt /var/run/furt
|
||||||
|
```
|
||||||
|
|
||||||
**Konfigurations-Struktur:**
|
## Source-Code installieren
|
||||||
- `[server]` - HTTP-Server-Parameter
|
|
||||||
- `[smtp_default]` - Standard-SMTP-Einstellungen
|
|
||||||
- `[api_key "name"]` - Mandanten-spezifische API-Schlüssel
|
|
||||||
|
|
||||||
**Basis-Konfiguration erstellen:**
|
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.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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:
|
||||||
|
|
||||||
*OpenBSD/FreeBSD* - `/usr/local/etc/furt/furt.conf`:
|
|
||||||
```ini
|
```ini
|
||||||
# furt Multi-Mandanten-Konfiguration
|
|
||||||
|
|
||||||
[server]
|
|
||||||
host = 127.0.0.1
|
|
||||||
port = 7811
|
|
||||||
log_level = info
|
|
||||||
|
|
||||||
[smtp_default]
|
[smtp_default]
|
||||||
host = mail.dragons-at-work.de
|
host = mail.example.com
|
||||||
port = 465
|
user = noreply@example.com
|
||||||
user = noreply@dragons-at-work.de
|
password = your-smtp-password-here
|
||||||
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`:
|
Der `[api_key]`-Abschnitt definiert welche Websites furt nutzen dürfen und wohin deren Mails weitergeleitet werden:
|
||||||
|
|
||||||
```ini
|
```ini
|
||||||
# Identische Konfiguration wie oben
|
[api_key "website-key"]
|
||||||
|
name = "Ihre Website"
|
||||||
|
mail_to = admin@example.com
|
||||||
|
mail_from = noreply@example.com
|
||||||
```
|
```
|
||||||
|
|
||||||
**Sicherheits-Berechtigungen für Produktion:**
|
Da die Konfigurationsdatei SMTP-Passwörter enthält, beschränken wir den Zugriff auf Root und die furt-Gruppe:
|
||||||
|
|
||||||
*OpenBSD/FreeBSD:*
|
|
||||||
```bash
|
```bash
|
||||||
chmod 640 /usr/local/etc/furt/furt.conf
|
# OpenBSD Berechtigungen
|
||||||
chown root:_furt /usr/local/etc/furt/furt.conf
|
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
|
||||||
```
|
```
|
||||||
|
|
||||||
*Linux:*
|
## Service integrieren
|
||||||
```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:
|
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:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Temporär für Testing
|
doas cp deployment/openbsd/rc.d-furt /etc/rc.d/furt
|
||||||
chmod 644 /usr/local/etc/furt/furt.conf # OpenBSD/FreeBSD
|
doas chmod +x /etc/rc.d/furt
|
||||||
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
|
echo "furt_flags=" >> /etc/rc.conf.local
|
||||||
rcctl enable furt
|
doas rcctl enable furt
|
||||||
```
|
```
|
||||||
|
|
||||||
**Das Template `deployment/openbsd/rc.d-furt` enthält:**
|
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.
|
||||||
- Service-vs-Interactive-Detection über `start.sh`
|
|
||||||
- Korrekte Daemon-Konfiguration für OpenBSD
|
Unter Linux verwenden wir systemd:
|
||||||
- Prozess-Pattern für `rcctl`-Integration
|
|
||||||
|
|
||||||
**Linux systemd-Unit aus Repository-Template:**
|
|
||||||
```bash
|
```bash
|
||||||
# Template aus Repository verwenden
|
sudo cp deployment/linux/furt.service /etc/systemd/system/
|
||||||
cp deployment/linux/furt.service /etc/systemd/system/
|
sudo systemctl daemon-reload
|
||||||
systemctl daemon-reload
|
sudo systemctl enable furt
|
||||||
systemctl enable furt
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Das Template `deployment/linux/furt.service` enthält:**
|
Der `daemon-reload` ist notwendig damit systemd die neue Service-Datei erkennt.
|
||||||
- Service-vs-Interactive-Detection über `start.sh`
|
|
||||||
- Korrekte User/Group-Konfiguration für Linux
|
## Service starten und testen
|
||||||
- Restart-Policy für systemd-Integration
|
|
||||||
|
Jetzt können wir furt starten und die Installation testen:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
## Installation validieren
|
||||||
|
|
||||||
### Service starten und Status prüfen
|
Ein erfolgreicher Health-Check bestätigt dass furt läuft und alle Module korrekt geladen sind:
|
||||||
|
|
||||||
**OpenBSD:**
|
|
||||||
```bash
|
|
||||||
rcctl start furt
|
|
||||||
rcctl check furt
|
|
||||||
```
|
|
||||||
|
|
||||||
**Linux:**
|
|
||||||
```bash
|
|
||||||
systemctl start furt
|
|
||||||
systemctl status furt
|
|
||||||
```
|
|
||||||
|
|
||||||
### Health-Check durchführen
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl http://127.0.0.1:7811/health
|
curl http://127.0.0.1:7811/health
|
||||||
```
|
```
|
||||||
|
|
||||||
**Erwartete Response:**
|
Die Response zeigt Service-Status, Version und verfügbare Features. Um die Mail-Funktionalität zu testen, sende eine Test-Mail:
|
||||||
```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
|
```bash
|
||||||
curl -X POST http://127.0.0.1:7811/v1/mail/send \
|
curl -X POST http://127.0.0.1:7811/v1/mail/send \
|
||||||
-H "X-API-Key: daw-frontend-key" \
|
-H "X-API-Key: website-key" \
|
||||||
-H "Content-Type: application/json" \
|
-H "Content-Type: application/json" \
|
||||||
-d '{
|
-d '{
|
||||||
"name": "Installation Test",
|
"name": "Installation Test",
|
||||||
"email": "test@example.com",
|
"email": "test@example.com",
|
||||||
"subject": "furt Installation erfolgreich",
|
"subject": "furt Test",
|
||||||
"message": "Das furt API-Gateway ist betriebsbereit."
|
"message": "Installation erfolgreich"
|
||||||
}'
|
}'
|
||||||
```
|
```
|
||||||
|
|
||||||
**Erfolgreiche Response:**
|
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.
|
||||||
```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.
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue