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
|
||||
|
||||
### Option 1: Paket-Download (Empfohlen)
|
||||
|
||||
furt wird als versionierte Pakete über den Dragons@Work Package-Server bereitgestellt. Diese Methode ist für Produktions-Installationen empfohlen.
|
||||
|
||||
**Aktuelles Paket herunterladen:**
|
||||
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.
|
||||
|
||||
```bash
|
||||
# Paket in temporäres Verzeichnis downloaden
|
||||
mkdir -p /tmp/furt-install
|
||||
cd /tmp/furt-install
|
||||
|
||||
# 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
|
||||
# Package-Download
|
||||
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
|
||||
tar -xzf furt-api-gateway-v0.1.2.tar.gz
|
||||
cd furt-api-gateway-v0.1.2
|
||||
```
|
||||
|
||||
**Paket-Integrität prüfen:**
|
||||
Alternativ kannst du das Git-Repository clonen:
|
||||
|
||||
```bash
|
||||
# merkwerk-Signature validieren (falls verfügbar)
|
||||
if [ -f .version_history ]; then
|
||||
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
|
||||
git clone https://smida.dragons-at-work.de/DAW/furt.git
|
||||
cd furt
|
||||
```
|
||||
|
||||
**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
|
||||
# Repository clonen
|
||||
git clone https://smida.dragons-at-work.de/DAW/furt.git /tmp/furt-source
|
||||
cd /tmp/furt-source
|
||||
# OpenBSD nutzt _furt als Benutzerkonvention
|
||||
doas groupadd _furt
|
||||
doas useradd -g _furt -s /bin/false -d /var/empty _furt
|
||||
```
|
||||
|
||||
**Repository-Struktur validieren:**
|
||||
```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:**
|
||||
Die Shell `/bin/false` verhindert Login-Versuche auf diesen Account. Das Home-Verzeichnis `/var/empty` ist ein leeres, unveränderliches Verzeichnis.
|
||||
|
||||
```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')"
|
||||
# Linux nutzt furt als System-Benutzer
|
||||
sudo groupadd --system furt
|
||||
sudo useradd --system -g furt -s /bin/false -d /var/empty furt
|
||||
```
|
||||
|
||||
**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:*
|
||||
```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:**
|
||||
Jetzt erstellen wir die benötigten Verzeichnisse mit korrekten Berechtigungen:
|
||||
|
||||
```bash
|
||||
# start.sh-Funktionalität testen
|
||||
cd /usr/local/share/furt
|
||||
./scripts/start.sh
|
||||
# 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
|
||||
|
||||
# Erwartete Ausgabe:
|
||||
# Auto-detected lua command: lua
|
||||
# Furt HTTP-Server started on 127.0.0.1:7811
|
||||
# [...]
|
||||
# furt-Benutzer braucht Schreibrechte für Logs und PID-Dateien
|
||||
doas chown _furt:_furt /var/log/furt
|
||||
doas chown _furt:_furt /var/run/furt
|
||||
```
|
||||
|
||||
**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
|
||||
Unter Linux ist die Struktur identisch, nur das Config-Verzeichnis liegt direkt in `/etc/`:
|
||||
|
||||
### 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:**
|
||||
- `[server]` - HTTP-Server-Parameter
|
||||
- `[smtp_default]` - Standard-SMTP-Einstellungen
|
||||
- `[api_key "name"]` - Mandanten-spezifische API-Schlüssel
|
||||
## Source-Code installieren
|
||||
|
||||
**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
|
||||
# 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
|
||||
host = mail.example.com
|
||||
user = noreply@example.com
|
||||
password = your-smtp-password-here
|
||||
```
|
||||
|
||||
*Linux* - `/etc/furt/furt.conf`:
|
||||
Der `[api_key]`-Abschnitt definiert welche Websites furt nutzen dürfen und wohin deren Mails weitergeleitet werden:
|
||||
|
||||
```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
|
||||
chmod 640 /usr/local/etc/furt/furt.conf
|
||||
chown root:_furt /usr/local/etc/furt/furt.conf
|
||||
# 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
|
||||
```
|
||||
|
||||
*Linux:*
|
||||
```bash
|
||||
chmod 640 /etc/furt/furt.conf
|
||||
chown root:furt /etc/furt/furt.conf
|
||||
```
|
||||
## Service integrieren
|
||||
|
||||
**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
|
||||
# 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
|
||||
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
|
||||
rcctl enable furt
|
||||
doas 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
|
||||
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:
|
||||
|
||||
**Linux systemd-Unit aus Repository-Template:**
|
||||
```bash
|
||||
# Template aus Repository verwenden
|
||||
cp deployment/linux/furt.service /etc/systemd/system/
|
||||
systemctl daemon-reload
|
||||
systemctl enable furt
|
||||
sudo cp deployment/linux/furt.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable furt
|
||||
```
|
||||
|
||||
**Das Template `deployment/linux/furt.service` enthält:**
|
||||
- Service-vs-Interactive-Detection über `start.sh`
|
||||
- Korrekte User/Group-Konfiguration für Linux
|
||||
- Restart-Policy für systemd-Integration
|
||||
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:
|
||||
|
||||
```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
|
||||
|
||||
### 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
|
||||
Ein erfolgreicher Health-Check bestätigt dass furt läuft und alle Module korrekt geladen sind:
|
||||
|
||||
```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
|
||||
Die Response zeigt Service-Status, Version und verfügbare Features. Um die Mail-Funktionalität zu testen, sende eine Test-Mail:
|
||||
|
||||
```bash
|
||||
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" \
|
||||
-d '{
|
||||
"name": "Installation Test",
|
||||
"email": "test@example.com",
|
||||
"subject": "furt Installation erfolgreich",
|
||||
"message": "Das furt API-Gateway ist betriebsbereit."
|
||||
"subject": "furt Test",
|
||||
"message": "Installation erfolgreich"
|
||||
}'
|
||||
```
|
||||
|
||||
**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.
|
||||
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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue