Installation hinzugefügt
parent
c0feed3ab8
commit
0a18fc5db8
1 changed files with 442 additions and 0 deletions
442
Installation.md
Normal file
442
Installation.md
Normal file
|
|
@ -0,0 +1,442 @@
|
|||
# Installation
|
||||
|
||||
## 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
|
||||
|
||||
## Systemanforderungen verstehen
|
||||
|
||||
### Lua 5.1 Requirement
|
||||
|
||||
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.
|
||||
|
||||
### Warum ein eigener Benutzer
|
||||
|
||||
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
|
||||
|
||||
Der Unterstrich-Prefix markiert System-Benutzer (Konvention).
|
||||
|
||||
### Warum diese Verzeichnis-Struktur
|
||||
|
||||
**Konfigurations-Verzeichnis:**
|
||||
- BSD: `/usr/local/etc/furt/` (Package-Namensraum)
|
||||
- Linux: `/etc/furt/` (Einheitlicher Namensraum)
|
||||
|
||||
**Log-Verzeichnis:** `/var/log/furt/`
|
||||
- Standard-Pfad für System-Logs
|
||||
|
||||
**Anwendungs-Verzeichnis:** `/usr/local/share/furt/`
|
||||
- Schreibgeschützte Programm-Dateien
|
||||
- Getrennt von Konfiguration und Protokollen
|
||||
- Standard-Location für Architektur-unabhängige Daten
|
||||
|
||||
### Berechtigungs-Modell
|
||||
|
||||
**Konfigurations-Dateien:** 644 root:root (644 root:wheel auf BSD)
|
||||
- Lesbar für Dienst, nicht änderbar
|
||||
- System-Administrator kann Konfiguration bearbeiten
|
||||
|
||||
**Vertrauliche Daten:** 600 root:root
|
||||
- Nur Root-Lesezugriff
|
||||
- API-Keys und SMTP-Passwörter isoliert
|
||||
|
||||
**Protokolle:** 755 _furt:_furt
|
||||
- Dienst kann eigene Protokolle schreiben
|
||||
- Andere Benutzer können Protokolle lesen (für Debugging)
|
||||
|
||||
## 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:**
|
||||
```
|
||||
/usr/local/etc/furt/furt.conf # Package-Konfigurations-Namensraum
|
||||
/usr/local/share/furt/ # Anwendungs-Dateien
|
||||
/var/log/furt/ # Standard Log-Location
|
||||
```
|
||||
|
||||
### 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:**
|
||||
```
|
||||
/etc/furt/furt.conf # Einheitlicher Konfigurations-Namensraum
|
||||
/usr/local/share/furt/ # Anwendungs-Dateien
|
||||
/var/log/furt/ # Standard Log-Location
|
||||
```
|
||||
|
||||
**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/)
|
||||
|
||||
## Manuelle Installation Schritt für Schritt
|
||||
|
||||
### 1. Abhängigkeiten installieren
|
||||
|
||||
```bash
|
||||
# OpenBSD (lua 5.1 ist Standard)
|
||||
pkg_add lua lua-socket lua-cjson
|
||||
|
||||
# FreeBSD
|
||||
pkg install lua51 lua51-luasocket lua51-lua-cjson
|
||||
|
||||
# Debian/Ubuntu
|
||||
apt install lua5.1 lua-socket lua-cjson
|
||||
|
||||
# Arch
|
||||
pacman -S lua51 lua51-socket lua51-cjson
|
||||
```
|
||||
|
||||
### 2. Dienst-Benutzer erstellen
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
**Warum diese Parameter:**
|
||||
- `-s /bin/false`: Kein Shell-Login möglich
|
||||
- `-d /nonexistent`: Kein Home-Verzeichnis
|
||||
- `-r`: System-Account (Linux)
|
||||
|
||||
### 3. Verzeichnis-Struktur erstellen
|
||||
|
||||
```bash
|
||||
# BSD-Systeme
|
||||
mkdir -p /usr/local/etc/furt/secrets
|
||||
mkdir -p /usr/local/share/furt
|
||||
mkdir -p /var/log/furt
|
||||
|
||||
# Linux-Systeme
|
||||
mkdir -p /etc/furt/secrets
|
||||
mkdir -p /usr/local/share/furt
|
||||
mkdir -p /var/log/furt
|
||||
```
|
||||
|
||||
### 4. Berechtigungen setzen
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 5. Anwendungs-Dateien kopieren
|
||||
|
||||
```bash
|
||||
# Quell-Dateien ins Anwendungs-Verzeichnis
|
||||
cp -r src/ /usr/local/share/furt/
|
||||
cp -r config/ /usr/local/share/furt/
|
||||
|
||||
# Lua-Dateien ausführbar machen
|
||||
chmod +x /usr/local/share/furt/src/main.lua
|
||||
```
|
||||
|
||||
### 6. Konfiguration erstellen
|
||||
|
||||
```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
|
||||
|
||||
chmod +x /usr/local/etc/rc.d/furt
|
||||
```
|
||||
|
||||
#### Linux (systemd)
|
||||
```bash
|
||||
# Dienst-Unit erstellen
|
||||
cat > /etc/systemd/system/furt.service << 'EOF'
|
||||
[Unit]
|
||||
Description=Furt 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
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
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
|
||||
systemctl start furt
|
||||
```
|
||||
|
||||
### 9. Funktionstest
|
||||
|
||||
```bash
|
||||
# Dienst-Status
|
||||
# OpenBSD: rcctl check furt
|
||||
# FreeBSD: service furt status
|
||||
# Linux: systemctl status furt
|
||||
|
||||
# HTTP-Endpunkt
|
||||
curl http://localhost:7811/health
|
||||
```
|
||||
|
||||
Erwartete Antwort:
|
||||
```json
|
||||
{"status":"healthy","service":"furt-lua","version":"1.0.0"}
|
||||
```
|
||||
|
||||
## Hilfsskripte (Optional)
|
||||
|
||||
Diese manuellen Schritte lassen sich durch modulare Hilfsskripte automatisieren:
|
||||
|
||||
- **`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
|
||||
```
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
**Typische Fehlermeldungen:**
|
||||
|
||||
*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
|
||||
|
||||
*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
|
||||
|
||||
*Ungültige SMTP-Konfiguration:*
|
||||
```
|
||||
Warning: No default SMTP configured, using localhost:25
|
||||
```
|
||||
→ `[smtp_default]` Sektion vervollständigen
|
||||
|
||||
### Prozess läuft nicht
|
||||
|
||||
**Diagnose-Kommandos:**
|
||||
```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
|
||||
```
|
||||
|
||||
**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:
|
||||
```bash
|
||||
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/
|
||||
```
|
||||
|
||||
### HTTP-Endpunkt nicht erreichbar
|
||||
|
||||
**Verbindungstest:**
|
||||
```bash
|
||||
# Lokaler Test
|
||||
curl -v http://localhost:7811/health
|
||||
|
||||
# Netzwerk-Test (von anderem Rechner)
|
||||
curl -v http://SERVER_IP:7811/health
|
||||
```
|
||||
|
||||
**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:**
|
||||
```bash
|
||||
# OpenBSD: /etc/pf.conf erweitern
|
||||
pass in on egress proto tcp to port 7811
|
||||
|
||||
# Linux: iptables oder ufw
|
||||
ufw allow 7811
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue