Dokumentation: OpenBSD rc.d Service-File Fix und Deployment-Workflow #79

New issue

Closed

opened 2025-06-23 19:51:29 +02:00 by Michael · 1 comment

Michael commented

2025-06-23 19:51:29 +02:00

(Migrated from gitea.dragons-at-work.de)

Zweck

Die Lösung für Issue #77 (OpenBSD rc.d Service-Tracking) muss dokumentiert werden, damit zukünftige Entwickler und Deployer die Hintergründe verstehen.

Zu dokumentierende Erkenntnisse

1. OpenBSD rc.d pexp-Problem

Problem: OpenBSD rc.subr überschreibt automatisch das pexp Pattern:

# rc.subr generiert automatisch:
pexp="$(eval echo ${daemon}${daemon_flags:+ ${daemon_flags}})"
# Ergebnis: "/usr/local/furt/furt-lua/scripts/start.sh start"

Aber der tatsächliche Prozess ist:

/usr/local/bin/lua src/main.lua (lua51)

Lösung: pexp NACH rc.subr überschreiben:

#!/bin/ksh
daemon="/usr/local/furt/furt-lua/scripts/start.sh"
daemon_user="_furt"
daemon_flags="start"

. /etc/rc.d/rc.subr

# pexp NACH rc.subr überschreiben (Fix für Issue #77)
pexp="/usr/local/bin/lua src/main.lua.*"

rc_cmd $1

2. TTY-basierte Daemon-Detection

Problem: Service muss sowohl interaktiv (karl) als auch als Daemon (walter) laufen.

Lösung: TTY-Detection in start.sh:

if [ ! -t 0 ]; then
    # No TTY = Service mode (rcctl)
    echo "Starting Furt in daemon mode..."
    $LUA_CMD src/main.lua &
    echo "Furt started (PID: $!)"
else
    # Interactive mode (manual/development)
    echo "Furt HTTP-Server started on 127.0.0.1:8080"
    echo "Press Ctrl+C to stop"
    $LUA_CMD src/main.lua
fi

3. Deployment-Workflow

Vollständiger karl→walter Deployment-Zyklus:

Service-Detection und Stop
Backup erstellen
File-Sync via rsync
Service-File deployment
Permissions fix
Service start
Health-Check validation
Backup cleanup

Zu erstellende Dokumentation

1. `docs/deployment/openbsd-rcctl.md`

OpenBSD rc.d Spezifikationen
pexp-Pattern-Matching Erklärung
Troubleshooting Guide
Common Pitfalls

2. `docs/deployment/karl-walter-workflow.md`

Complete Deployment Guide
Prerequisites (SSH, permissions)
Backup/Rollback Procedures
Health-Check Validation

3. `docs/development/service-modes.md`

TTY-Detection Logic
Interactive vs Daemon Mode
Development vs Production Unterschiede

4. `README.md` Update

OpenBSD Deployment Section
Quick Start Guide
Troubleshooting Links

Code-Kommentare erweitern

Alle kritischen Code-Stellen mit ausführlichen Kommentaren:

# deployment/openbsd/rc.d-furt
# CRITICAL: pexp MUST be set AFTER sourcing rc.subr
# OpenBSD rc.subr automatically overwrites pexp with daemon+flags
# but our actual process differs from the wrapper script

Akzeptanzkriterien

OpenBSD rc.d Dokumentation erstellt
Deployment-Workflow dokumentiert
Service-Mode Detection dokumentiert
README.md erweitert
Code-Kommentare hinzugefügt
Troubleshooting Guide erstellt

Technische Notes

Diese Dokumentation verhindert, dass zukünftige Entwickler die gleichen stundenlangen Debugging-Sessions durchlaufen müssen.

## Zweck Die Lösung für Issue #77 (OpenBSD rc.d Service-Tracking) muss dokumentiert werden, damit zukünftige Entwickler und Deployer die Hintergründe verstehen. ## Zu dokumentierende Erkenntnisse ### 1. OpenBSD rc.d pexp-Problem **Problem:** OpenBSD `rc.subr` überschreibt automatisch das `pexp` Pattern: ```bash # rc.subr generiert automatisch: pexp="$(eval echo ${daemon}${daemon_flags:+ ${daemon_flags}})" # Ergebnis: "/usr/local/furt/furt-lua/scripts/start.sh start" ``` **Aber der tatsächliche Prozess ist:** ``` /usr/local/bin/lua src/main.lua (lua51) ``` **Lösung:** `pexp` NACH `rc.subr` überschreiben: ```bash #!/bin/ksh daemon="/usr/local/furt/furt-lua/scripts/start.sh" daemon_user="_furt" daemon_flags="start" . /etc/rc.d/rc.subr # pexp NACH rc.subr überschreiben (Fix für Issue #77) pexp="/usr/local/bin/lua src/main.lua.*" rc_cmd $1 ``` ### 2. TTY-basierte Daemon-Detection **Problem:** Service muss sowohl interaktiv (karl) als auch als Daemon (walter) laufen. **Lösung:** TTY-Detection in `start.sh`: ```bash if [ ! -t 0 ]; then # No TTY = Service mode (rcctl) echo "Starting Furt in daemon mode..." $LUA_CMD src/main.lua & echo "Furt started (PID: $!)" else # Interactive mode (manual/development) echo "Furt HTTP-Server started on 127.0.0.1:8080" echo "Press Ctrl+C to stop" $LUA_CMD src/main.lua fi ``` ### 3. Deployment-Workflow **Vollständiger karl→walter Deployment-Zyklus:** 1. Service-Detection und Stop 2. Backup erstellen 3. File-Sync via rsync 4. Service-File deployment 5. Permissions fix 6. Service start 7. Health-Check validation 8. Backup cleanup ## Zu erstellende Dokumentation ### 1. `docs/deployment/openbsd-rcctl.md` - OpenBSD rc.d Spezifikationen - pexp-Pattern-Matching Erklärung - Troubleshooting Guide - Common Pitfalls ### 2. `docs/deployment/karl-walter-workflow.md` - Complete Deployment Guide - Prerequisites (SSH, permissions) - Backup/Rollback Procedures - Health-Check Validation ### 3. `docs/development/service-modes.md` - TTY-Detection Logic - Interactive vs Daemon Mode - Development vs Production Unterschiede ### 4. `README.md` Update - OpenBSD Deployment Section - Quick Start Guide - Troubleshooting Links ## Code-Kommentare erweitern Alle kritischen Code-Stellen mit ausführlichen Kommentaren: ```bash # deployment/openbsd/rc.d-furt # CRITICAL: pexp MUST be set AFTER sourcing rc.subr # OpenBSD rc.subr automatically overwrites pexp with daemon+flags # but our actual process differs from the wrapper script ``` ## Akzeptanzkriterien - [ ] OpenBSD rc.d Dokumentation erstellt - [ ] Deployment-Workflow dokumentiert - [ ] Service-Mode Detection dokumentiert - [ ] README.md erweitert - [ ] Code-Kommentare hinzugefügt - [ ] Troubleshooting Guide erstellt ## Technische Notes Diese Dokumentation verhindert, dass zukünftige Entwickler die gleichen stundenlangen Debugging-Sessions durchlaufen müssen.