DAW/furt

Fork 0

Fix: Installation.md Service-Integration und Plattform-Kompatibilität #98

New issue

Closed

opened 2025-09-01 21:19:16 +02:00 by michael · 2 comments

michael commented

2025-09-01 21:19:16 +02:00

Owner

Problem

Installation.md hat mehrere fundamentale Fehler die eine funktionierende Service-Installation verhindern.

Testing-Ergebnis auf werner:

✅ Repository-Clone funktioniert
✅ User/Verzeichnisse-Erstellung funktioniert
✅ Source-Code-Installation funktioniert
✅ Manual furt-Start funktioniert
❌ Service-Integration komplett defekt

Identifizierte Probleme

1. Command-Inkonsistenz (OpenBSD)

Problem:

# Installation.md schreibt:
lua5.1 -v
lua5.1 -e "require('socket')"

# OpenBSD hat:
lua -v        # nicht lua5.1

Impact: Systemanforderungen-Check schlägt fehl.

2. rc.d Service-Integration defekt

Problem: Installation.md Service-Script funktioniert nicht:

#!/bin/ksh
daemon="/usr/local/bin/furt"
daemon_flags=""
daemon_user="_furt"
daemon_logger="daemon.info"
. /etc/rc.d/rc.subr
rc_cmd $1

Symptom:

rcctl start furt hängt endlos
Service nie erfolgreich startbar
Keine funktionierende Service-Integration

3. Wrapper-Script Pattern ungeeignet

Problem: /usr/local/bin/furt Wrapper-Script:

#!/bin/sh
export LUA_PATH="/usr/local/share/furt/?.lua;;"
cd /usr/local/share/furt
exec lua src/main.lua "$@"

Defekte:

Funktioniert interaktiv ✅
Funktioniert als Daemon ❌ (hängt)
exec + Environment-Changes + Working Directory im Service-Context problematisch

4. Config-Berechtigungen vs Testing

Problem: Installation.md setzt:

chmod 640 /usr/local/etc/furt/furt.conf
chown root:_furt /usr/local/etc/furt/furt.conf

Aber testet als:

/usr/local/bin/furt  # als michael user

Resultat: Config nicht lesbar, Testing schlägt fehl.

5. Unvollständige Repository-Dokumentation

Problem: Installation.md erwähnt nicht:

integrations/ Verzeichnis
tests/ Verzeichnis
docs/ Verzeichnis
.env.example Datei
deployment/ Verzeichnis

Impact: Incomplete Installation möglich.

Lösungsansätze

1. Command-Detection

# Statt fester lua5.1 - Detection:
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 "No Lua found"
    exit 1
fi

2. Derzeit unter openBSD lauffähige rc.d Service

#!/bin/ksh

daemon="/usr/local/share/furt/scripts/start.sh"
daemon_user="_furt"
daemon_cwd="/usr/local/share/furt"
daemon_flags="start"

. /etc/rc.d/rc.subr

pexp="lua.*src/main.lua"

rc_cmd $1

3. Service-Detection in start.sh

Siehe Issue DAW/furt#99 - start.sh braucht Service vs Interactive Detection. -> bereits integriert.

4. Testing-Config

# Für Testing temporär lesbar:
doas chmod 644 /usr/local/etc/furt/furt.conf

# Für Produktion:  
doas chmod 640 /usr/local/etc/furt/furt.conf

Oder man testet, wie gestern geschehen als user _furt ... dann passt es auch und man muss keine Berechtigungen ändern.

5. Vollständige Datei-Liste

Installation.md sollte alle Repository-Verzeichnisse dokumentieren.

Prioritäten

High Priority:

Service-Integration reparieren
Command-Detection implementieren

Medium Priority:

Config-Berechtigungen korrigieren
Repository-Dokumentation vervollständigen

Testing Required:

OpenBSD ✅ (getestet auf werner)
Debian/Ubuntu (noch zu testen)
Arch Linux (noch zu testen)

Betroffene Dateien

Installation.md (Hauptdokumentation)
Möglicherweise Template-rc.d-Scripts

Impact: Installation.md ist nicht produktionstauglich in aktueller Form.

## Problem Installation.md hat mehrere fundamentale Fehler die eine funktionierende Service-Installation verhindern. **Testing-Ergebnis auf werner:** - ✅ Repository-Clone funktioniert - ✅ User/Verzeichnisse-Erstellung funktioniert - ✅ Source-Code-Installation funktioniert - ✅ Manual furt-Start funktioniert - ❌ Service-Integration komplett defekt ## Identifizierte Probleme ### 1. Command-Inkonsistenz (OpenBSD) **Problem:** ```bash # Installation.md schreibt: lua5.1 -v lua5.1 -e "require('socket')" # OpenBSD hat: lua -v # nicht lua5.1 ``` **Impact:** Systemanforderungen-Check schlägt fehl. ### 2. rc.d Service-Integration defekt **Problem:** Installation.md Service-Script funktioniert nicht: ```bash #!/bin/ksh daemon="/usr/local/bin/furt" daemon_flags="" daemon_user="_furt" daemon_logger="daemon.info" . /etc/rc.d/rc.subr rc_cmd $1 ``` **Symptom:** - `rcctl start furt` hängt endlos - Service nie erfolgreich startbar - Keine funktionierende Service-Integration ### 3. Wrapper-Script Pattern ungeeignet **Problem:** `/usr/local/bin/furt` Wrapper-Script: ```bash #!/bin/sh export LUA_PATH="/usr/local/share/furt/?.lua;;" cd /usr/local/share/furt exec lua src/main.lua "$@" ``` **Defekte:** - Funktioniert interaktiv ✅ - Funktioniert als Daemon ❌ (hängt) - `exec` + Environment-Changes + Working Directory im Service-Context problematisch ### 4. Config-Berechtigungen vs Testing **Problem:** Installation.md setzt: ```bash chmod 640 /usr/local/etc/furt/furt.conf chown root:_furt /usr/local/etc/furt/furt.conf ``` **Aber testet als:** ```bash /usr/local/bin/furt # als michael user ``` **Resultat:** Config nicht lesbar, Testing schlägt fehl. ### 5. Unvollständige Repository-Dokumentation **Problem:** Installation.md erwähnt nicht: - `integrations/` Verzeichnis - `tests/` Verzeichnis - `docs/` Verzeichnis - `.env.example` Datei - `deployment/` Verzeichnis **Impact:** Incomplete Installation möglich. ## Lösungsansätze ### 1. Command-Detection ```bash # Statt fester lua5.1 - Detection: 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 "No Lua found" exit 1 fi ``` ### 2. Derzeit unter openBSD lauffähige rc.d Service ```bash #!/bin/ksh daemon="/usr/local/share/furt/scripts/start.sh" daemon_user="_furt" daemon_cwd="/usr/local/share/furt" daemon_flags="start" . /etc/rc.d/rc.subr pexp="lua.*src/main.lua" rc_cmd $1 ``` ### 3. Service-Detection in start.sh Siehe Issue DAW/furt#99 - start.sh braucht Service vs Interactive Detection. -> bereits integriert. ### 4. Testing-Config ```bash # Für Testing temporär lesbar: doas chmod 644 /usr/local/etc/furt/furt.conf # Für Produktion: doas chmod 640 /usr/local/etc/furt/furt.conf ``` Oder man testet, wie gestern geschehen als user _furt ... dann passt es auch und man muss keine Berechtigungen ändern. ### 5. Vollständige Datei-Liste Installation.md sollte alle Repository-Verzeichnisse dokumentieren. ## Prioritäten **High Priority:** - Service-Integration reparieren - Command-Detection implementieren **Medium Priority:** - Config-Berechtigungen korrigieren - Repository-Dokumentation vervollständigen **Testing Required:** - OpenBSD ✅ (getestet auf werner) - Debian/Ubuntu (noch zu testen) - Arch Linux (noch zu testen) ## Betroffene Dateien - `Installation.md` (Hauptdokumentation) - Möglicherweise Template-rc.d-Scripts **Impact:** Installation.md ist nicht produktionstauglich in aktueller Form.

michael added the

labels 2025-09-01 21:19:16 +02:00

michael added this to the v0.1.2 - Gateway Basics milestone 2025-09-02 18:38:18 +02:00

michael commented

2025-09-02 19:46:13 +02:00

Author

Owner

Fehlende Source-Beschaffung in Installation.md

Problem identifiziert während werner-Testing:

Die Installation.md beginnt direkt mit Schritt 1 "Systemanforderungen prüfen", aber erklärt nicht woher die furt-Quellen kommen.

Aktueller Zustand

Installation.md Schritt 3:

# Haupt-Bibliothek installieren
cp -r src/ /usr/local/share/furt/
cp -r config/ /usr/local/share/furt/

Problem: Woher kommen src/ und config/? Die Anleitung setzt voraus, dass sie bereits vorhanden sind.

Werner-Testing Lösung

Wir haben das Repository geclont:

git clone https://smida.dragons-at-work.de/DAW/furt.git /tmp/furt-test
cd /tmp/furt-test
ls -la  # src/, config/, scripts/ etc. verfügbar

Fehlender Installations-Schritt

Installation.md braucht Schritt 0: Source-Beschaffung

Option A: Git-Repository (Development/Testing)

# Repository clonen
git clone https://smida.dragons-at-work.de/DAW/furt.git /tmp/furt-source
cd /tmp/furt-source

# Dann weiter mit Installation.md Schritt 1

Option B: Release-Archive (Production)

# Release-Tarball herunterladen (wenn verfügbar)
curl -L https://smida.dragons-at-work.de/DAW/furt/archive/v0.1.1.tar.gz | tar xz
cd furt-0.1.1/

# Dann weiter mit Installation.md Schritt 1

Option C: Package-Installation (Zukunft)

# OpenBSD Package (geplant)
pkg_add furt

# Debian Package (geplant)  
apt install furt

Repository-Struktur dokumentieren

Die Installation.md sollte auch die erwartete Verzeichnisstruktur zeigen:

furt/
├── src/                    # Lua-Quellcode
│   ├── main.lua
│   ├── config_parser.lua
│   └── ...
├── config/                 # Konfigurationsbeispiele
│   └── furt.conf.example
├── scripts/                # Helper-Scripts
│   └── start.sh
├── docs/                   # Dokumentation
├── tests/                  # Test-Suite
├── integrations/           # merkwerk-Integration
├── .env.example           # Environment-Beispiele
├── VERSION                # Version-Info
└── .version_history       # merkwerk-History

Authentifizierungs-Problem

Repository-Zugang während werner-Testing:

Das Repository war anfangs private und benötigte Authentifizierung:

git clone https://smida.dragons-at-work.de/DAW/furt.git
# Username for 'https://smida.dragons-at-work.de': 
# Password for 'https://smida.dragons-at-work.de':

Lösung: Organisationseinstellungen auf public geändert.

Für Installation.md: Dokumentieren ob Repository public oder authentifizierung erforderlich ist.

URL-Inkonsistenz

Dokumentation erwähnt verschiedene URLs:

https://gitea.dragons-at-work.de (in alten Configs)
https://smida.dragons-at-work.de (tatsächliche URL)

Installation.md sollte konsistente, korrekte URLs verwenden.

Empfohlene Installation.md Erweiterung

Neuer Schritt 0 hinzufügen:

## Schritt 0: Source-Code beschaffen

### Option A: Git-Repository (Empfohlen für Testing)

```bash
# Repository clonen
git clone https://smida.dragons-at-work.de/DAW/furt.git /tmp/furt-source
cd /tmp/furt-source

# Repository-Struktur prüfen
ls -la
# Erwartet: src/, config/, scripts/, docs/, etc.

Option B: Release-Download (Production)

# Aktuellstes Release herunterladen
curl -L https://smida.dragons-at-work.de/DAW/furt/releases/latest/download/furt-src.tar.gz | tar xz
cd furt-*/

Verzeichnisstruktur validieren

Vor Installation prüfen:

# Erforderliche Verzeichnisse vorhanden?
ls -la src/main.lua config/furt.conf.example scripts/start.sh

Dann weiter mit Schritt 1: Systemanforderungen...


### Platform-spezifische Hinweise

**OpenBSD:** git standardmäßig nicht installiert
```bash
# Falls Git fehlt
doas pkg_add git

Debian/Ubuntu: git meist verfügbar

# Falls Git fehlt
apt install git

Testing-Empfehlung

Vor finaler Installation.md: Dokumentation an Clean-System testen:

Fresh VM ohne vorherige furt-Installation
Installation.md Schritt-für-Schritt befolgen
Alle Kommandos kopieren/ausführen ohne Anpassungen
Erfolg messen: Service läuft nach Reboot

Werner-Testing war erfolgreich, aber nur weil wir die Source-Beschaffung separat gelöst haben.

Betroffene Dokumentations-Abschnitte

Schritt 0 hinzufügen: Source-Beschaffung vor Systemanforderungen
URL-Konsistenz: Einheitliche Repository-URLs
Repository-Struktur: Erwartete Verzeichnisse dokumentieren
Authentifizierung: Public vs Private Repository-Zugang
Platform-Prerequisites: Git-Installation falls erforderlich

Impact: Installation.md ist unvollständig ohne Source-Beschaffungs-Anleitung.

## Fehlende Source-Beschaffung in Installation.md **Problem identifiziert während werner-Testing:** Die Installation.md beginnt direkt mit Schritt 1 "Systemanforderungen prüfen", aber erklärt nicht **woher die furt-Quellen kommen**. ### Aktueller Zustand **Installation.md Schritt 3:** ```bash # Haupt-Bibliothek installieren cp -r src/ /usr/local/share/furt/ cp -r config/ /usr/local/share/furt/ ``` **Problem:** Woher kommen `src/` und `config/`? Die Anleitung setzt voraus, dass sie bereits vorhanden sind. ### Werner-Testing Lösung Wir haben das Repository geclont: ```bash git clone https://smida.dragons-at-work.de/DAW/furt.git /tmp/furt-test cd /tmp/furt-test ls -la # src/, config/, scripts/ etc. verfügbar ``` ### Fehlender Installations-Schritt **Installation.md braucht Schritt 0: Source-Beschaffung** #### Option A: Git-Repository (Development/Testing) ```bash # Repository clonen git clone https://smida.dragons-at-work.de/DAW/furt.git /tmp/furt-source cd /tmp/furt-source # Dann weiter mit Installation.md Schritt 1 ``` #### Option B: Release-Archive (Production) ```bash # Release-Tarball herunterladen (wenn verfügbar) curl -L https://smida.dragons-at-work.de/DAW/furt/archive/v0.1.1.tar.gz | tar xz cd furt-0.1.1/ # Dann weiter mit Installation.md Schritt 1 ``` #### Option C: Package-Installation (Zukunft) ```bash # OpenBSD Package (geplant) pkg_add furt # Debian Package (geplant) apt install furt ``` ### Repository-Struktur dokumentieren **Die Installation.md sollte auch die erwartete Verzeichnisstruktur zeigen:** ``` furt/ ├── src/ # Lua-Quellcode │ ├── main.lua │ ├── config_parser.lua │ └── ... ├── config/ # Konfigurationsbeispiele │ └── furt.conf.example ├── scripts/ # Helper-Scripts │ └── start.sh ├── docs/ # Dokumentation ├── tests/ # Test-Suite ├── integrations/ # merkwerk-Integration ├── .env.example # Environment-Beispiele ├── VERSION # Version-Info └── .version_history # merkwerk-History ``` ### Authentifizierungs-Problem **Repository-Zugang während werner-Testing:** Das Repository war anfangs private und benötigte Authentifizierung: ```bash git clone https://smida.dragons-at-work.de/DAW/furt.git # Username for 'https://smida.dragons-at-work.de': # Password for 'https://smida.dragons-at-work.de': ``` **Lösung:** Organisationseinstellungen auf public geändert. **Für Installation.md:** Dokumentieren ob Repository public oder authentifizierung erforderlich ist. ### URL-Inkonsistenz **Dokumentation erwähnt verschiedene URLs:** - `https://gitea.dragons-at-work.de` (in alten Configs) - `https://smida.dragons-at-work.de` (tatsächliche URL) **Installation.md sollte konsistente, korrekte URLs verwenden.** ### Empfohlene Installation.md Erweiterung **Neuer Schritt 0 hinzufügen:** ```markdown ## Schritt 0: Source-Code beschaffen ### Option A: Git-Repository (Empfohlen für Testing) ```bash # Repository clonen git clone https://smida.dragons-at-work.de/DAW/furt.git /tmp/furt-source cd /tmp/furt-source # Repository-Struktur prüfen ls -la # Erwartet: src/, config/, scripts/, docs/, etc. ``` ### Option B: Release-Download (Production) ```bash # Aktuellstes Release herunterladen curl -L https://smida.dragons-at-work.de/DAW/furt/releases/latest/download/furt-src.tar.gz | tar xz cd furt-*/ ``` ### Verzeichnisstruktur validieren Vor Installation prüfen: ```bash # Erforderliche Verzeichnisse vorhanden? ls -la src/main.lua config/furt.conf.example scripts/start.sh ``` ### Dann weiter mit Schritt 1: Systemanforderungen... ``` ### Platform-spezifische Hinweise **OpenBSD:** git standardmäßig nicht installiert ```bash # Falls Git fehlt doas pkg_add git ``` **Debian/Ubuntu:** git meist verfügbar ```bash # Falls Git fehlt apt install git ``` ### Testing-Empfehlung **Vor finaler Installation.md:** Dokumentation an Clean-System testen: 1. **Fresh VM** ohne vorherige furt-Installation 2. **Installation.md Schritt-für-Schritt** befolgen 3. **Alle Kommandos kopieren/ausführen** ohne Anpassungen 4. **Erfolg messen:** Service läuft nach Reboot **Werner-Testing war erfolgreich**, aber nur weil wir die Source-Beschaffung separat gelöst haben. ### Betroffene Dokumentations-Abschnitte - **Schritt 0 hinzufügen:** Source-Beschaffung vor Systemanforderungen - **URL-Konsistenz:** Einheitliche Repository-URLs - **Repository-Struktur:** Erwartete Verzeichnisse dokumentieren - **Authentifizierung:** Public vs Private Repository-Zugang - **Platform-Prerequisites:** Git-Installation falls erforderlich **Impact:** Installation.md ist unvollständig ohne Source-Beschaffungs-Anleitung.

michael referenced this issue from a commit

2025-09-02 21:27:44 +02:00

fix(deployment): update OpenBSD rc.d template for current service architecture

michael added

and removed

labels 2025-09-02 21:28:38 +02:00

michael commented

2025-09-02 21:34:39 +02:00

Author

Owner

Issue Resolution - All Critical Problems Fixed

Completed Solutions

1. Command-Inkonsistenz (OpenBSD)
✅ Fixed: Installation.md now includes automatic Lua command detection (lua vs lua5.1)

2. Service-Integration defekt
✅ Fixed: Updated to use scripts/start.sh instead of broken wrapper scripts
✅ Fixed: Repository template deployment/openbsd/rc.d-furt updated with correct paths and pexp

3. Package Dependencies - MAJOR BUGS
✅ Critical Fix: Arch Linux lua51-cjson → lua51-dkjson (lua51-cjson doesn't exist)
✅ Critical Fix: Added missing SSL dependencies (lua51-sec, lua-sec, luasec)
✅ Verified: All package names tested on production systems (karl/Arch, aitvaras/Ubuntu, werner/OpenBSD)

4. Source-Beschaffung
✅ Fixed: Added Step 0 with Git repository clone instructions
✅ Fixed: Repository structure validation included

5. Template-rc.d-Scripts
✅ Fixed: Installation.md references deployment/openbsd/rc.d-furt template instead of inline scripts
✅ Maintenance: Future rc.d changes only need repository template updates

6. Config-Berechtigungen vs Testing
✅ Fixed: Both production and testing permission strategies documented

7. Repository Cleanup
✅ Fixed: Removed confusing .env.example - furt uses only furt.conf

Testing Status

✅ OpenBSD (werner) - Service integration functional
✅ Ubuntu (aitvaras) - Package names verified
✅ Arch (karl) - Package names corrected and tested
✅ SSL/SMTP - Functional on all platforms

Impact

Installation.md is now production-ready. Fresh-VM installation should work end-to-end on all supported platforms.

The critical service-integration problems that prevented functional installations are resolved.

Status: RESOLVED

## Issue Resolution - All Critical Problems Fixed ### Completed Solutions **1. Command-Inkonsistenz (OpenBSD)** ✅ **Fixed:** Installation.md now includes automatic Lua command detection (`lua` vs `lua5.1`) **2. Service-Integration defekt** ✅ **Fixed:** Updated to use `scripts/start.sh` instead of broken wrapper scripts ✅ **Fixed:** Repository template `deployment/openbsd/rc.d-furt` updated with correct paths and pexp **3. Package Dependencies - MAJOR BUGS** ✅ **Critical Fix:** Arch Linux `lua51-cjson` → `lua51-dkjson` (lua51-cjson doesn't exist) ✅ **Critical Fix:** Added missing SSL dependencies (`lua51-sec`, `lua-sec`, `luasec`) ✅ **Verified:** All package names tested on production systems (karl/Arch, aitvaras/Ubuntu, werner/OpenBSD) **4. Source-Beschaffung** ✅ **Fixed:** Added Step 0 with Git repository clone instructions ✅ **Fixed:** Repository structure validation included **5. Template-rc.d-Scripts** ✅ **Fixed:** Installation.md references `deployment/openbsd/rc.d-furt` template instead of inline scripts ✅ **Maintenance:** Future rc.d changes only need repository template updates **6. Config-Berechtigungen vs Testing** ✅ **Fixed:** Both production and testing permission strategies documented **7. Repository Cleanup** ✅ **Fixed:** Removed confusing `.env.example` - furt uses only `furt.conf` ### Testing Status - ✅ **OpenBSD** (werner) - Service integration functional - ✅ **Ubuntu** (aitvaras) - Package names verified - ✅ **Arch** (karl) - Package names corrected and tested - ✅ **SSL/SMTP** - Functional on all platforms ### Impact **Installation.md is now production-ready.** Fresh-VM installation should work end-to-end on all supported platforms. The critical service-integration problems that prevented functional installations are resolved. **Status: RESOLVED**

michael closed this issue

2025-09-02 21:34:39 +02:00

michael referenced this issue from a commit

2025-09-02 21:47:53 +02:00

chore: remove obsolete .env.example and add issue #98 reference