From b55d3aea2db8f2d82dcca127be940fdefa80afd4 Mon Sep 17 00:00:00 2001 From: michael Date: Wed, 10 Sep 2025 08:22:28 +0200 Subject: [PATCH] Installation Scripte aktualisiert --- Installation-Scripte.md | 163 ++++++++++++++++++++++++++++++---------- 1 file changed, 122 insertions(+), 41 deletions(-) diff --git a/Installation-Scripte.md b/Installation-Scripte.md index e16ca08..27454b1 100644 --- a/Installation-Scripte.md +++ b/Installation-Scripte.md @@ -1,75 +1,156 @@ # Installation-Scripte -**Helper Scripts für automatisierte furt-Installation** +**Helper Scripts für automatisierte furt-Installation verstehen und nutzen** ## Getestet unter - OpenBSD 7.7 - Debian 12 - Arch Linux -## Script-System verstehen +## Warum modulare Scripts? -Die furt-Helper-Scripts entstanden aus mehreren manuellen Installationen und automatisieren wiederkehrende Aufgaben. Jedes Script übernimmt einen spezifischen Aspekt der Installation und kann sowohl einzeln als auch als Teil der orchestrierten Installation verwendet werden. +Die furt-Helper-Scripts entstanden aus praktischer Notwendigkeit. Nach der dritten manuellen Installation auf verschiedenen Systemen wurde klar: Die gleichen Schritte immer wieder abzutippen ist fehleranfällig und zeitraubend. Aber statt ein monolithisches Installations-Script zu schreiben, entstand ein modulares System aus sechs spezialisierten Scripts. -Das modulare Design ermöglicht es einzelne Komponenten zu debuggen, zu erweitern oder bei Bedarf zu überspringen. Alle Scripts folgen POSIX-Shell-Konventionen für maximale Kompatibilität zwischen BSD- und Linux-Systemen. +Diese Modularität bringt konkrete Vorteile: Du kannst einzelne Schritte debuggen ohne das komplette System neu zu installieren. Ein Fehler bei der Service-Integration bedeutet nicht dass du Benutzer und Verzeichnisse neu anlegen musst. Updates können nur den Source-Code betreffen ohne Service-Konfiguration zu berühren. -## Script-Übersicht +Jedes Script übernimmt genau eine Aufgabe und tut sie gut. Das `setup-user.sh` versteht die Unterschiede zwischen OpenBSD `_furt` und Linux `furt` Benutzerkonventionen. Das `sync-files.sh` weiß welche Dateien kopiert werden müssen und welche Berechtigungen sie brauchen. Diese Spezialisierung macht jeden Baustein robust und verständlich. -Das `install.sh` Orchestrator-Script koordiniert sechs spezialisierte Helper Scripts: +## Wie Scripts zusammenarbeiten -### Fresh Installation (alle 6 Phasen) -1. **[setup-user.sh](setup-user-sh.md)** - System-Benutzer erstellen -2. **[setup-directories.sh](setup-directories-sh.md)** - Verzeichnisstruktur anlegen -3. **[sync-files.sh](sync-files-sh.md)** - Source-Code installieren -4. **[create-service.sh](create-service-sh.md)** - System-Service integrieren -5. **[validate-config.sh](validate-config-sh.md)** - Konfiguration validieren -6. **[health-check.sh](health-check-sh.md)** - Service-Status prüfen +Die sechs Helper Scripts folgen einer klaren Abhängigkeitskette. Das `setup-user.sh` muss vor `setup-directories.sh` laufen, weil die Verzeichnisse dem neu erstellten Benutzer gehören sollen. Das `sync-files.sh` benötigt die Verzeichnisstruktur aus dem vorherigen Schritt. Das `create-service.sh` sucht nach den kopierten Service-Templates aus `sync-files.sh`. -### Upgrade Installation (3 Phasen) +```bash +# Abhängigkeitskette bei Fresh Installation: +setup-user.sh # Erstellt _furt oder furt Benutzer + ↓ +setup-directories.sh # Nutzt Benutzer für chown-Operationen + ↓ +sync-files.sh # Kopiert in die erstellten Verzeichnisse + ↓ +create-service.sh # Verwendet die kopierten Service-Templates + ↓ +validate-config.sh # Prüft die installierte Konfiguration + ↓ +health-check.sh # Testet das Gesamtsystem +``` + +Diese Reihenfolge ist nicht willkürlich. Jedes Script baut auf den Ergebnissen des vorherigen auf. Das Orchestrator-Script `install.sh` stellt sicher dass diese Abhängigkeiten eingehalten werden und bricht ab wenn ein Schritt fehlschlägt. + +## Die sechs Installations-Phasen + +### Phase 1: System-Benutzer anlegen +**[setup-user.sh](setup-user-sh.md)** erkennt automatisch das Betriebssystem und erstellt den entsprechenden System-Benutzer. OpenBSD nutzt die `_servicename` Konvention für Sicherheits-Services, deshalb wird `_furt` angelegt. Linux-Distributionen verwenden meist den Service-Namen direkt, hier entsteht `furt` mit dem `--system` Flag. + +Das Script prüft ob der Benutzer bereits existiert und überspringt die Erstellung falls nötig. Diese Idempotenz macht das Script sicher für mehrfache Ausführung. + +### Phase 2: Verzeichnisstruktur erstellen +**[setup-directories.sh](setup-directories-sh.md)** legt die komplette furt-Verzeichnisstruktur an. Es versteht die Unterschiede zwischen BSD und Linux Filesystem-Konventionen: OpenBSD verwendet `/usr/local/etc/` für selbst-installierte Software um eine klare Trennung zur Basis-Installation zu schaffen. Linux-Distributionen legen alle Konfiguration in `/etc/`. + +```bash +# OpenBSD Struktur +/usr/local/etc/furt/ # Konfiguration +/usr/local/share/furt/ # Source-Code (read-only) +/var/log/furt/ # Logs (furt-writable) +/var/run/furt/ # PID-Files (furt-writable) + +# Linux Struktur +/etc/furt/ # Konfiguration +/usr/local/share/furt/ # Source-Code (read-only) +/var/log/furt/ # Logs (furt-writable) +/var/run/furt/ # PID-Files (furt-writable) +``` + +Das Script setzt auch die korrekten Berechtigungen: Der furt-Benutzer braucht Schreibrechte für Logs und PID-Files, aber nicht für den Source-Code oder die Konfiguration. + +### Phase 3: Source-Code synchronisieren +**[sync-files.sh](sync-files-sh.md)** kopiert den kompletten furt-Quellcode nach `/usr/local/share/furt/`. Es behandelt alle Dateitypen korrekt: Source-Dateien erhalten 644-Permissions, Verzeichnisse 755, ausführbare Scripts wie `start.sh` bekommen das Execute-Bit. + +Das Script kopiert auch Versions-Dateien für die merkwerk-Integration falls vorhanden. Diese Dateien ermöglichen es später nachzuvollziehen welche furt-Version installiert ist und wann Updates gemacht wurden. + +### Phase 4: Service integrieren +**[create-service.sh](create-service-sh.md)** installiert die passenden Service-Templates aus dem `deployment/`-Verzeichnis. Es erkennt automatisch ob das System OpenBSD (rc.d) oder Linux (systemd) nutzt und installiert das entsprechende Template. + +Unter OpenBSD wird das rc.d-Script nach `/etc/rc.d/furt` kopiert, ausführbar gemacht und mit `rcctl enable` für automatischen Start aktiviert. Unter Linux wird die systemd-Unit installiert, `daemon-reload` ausgeführt und der Service mit `systemctl enable` aktiviert. + +### Phase 5: Konfiguration validieren +**[validate-config.sh](validate-config-sh.md)** prüft ob eine gültige Konfigurationsdatei vorhanden ist. Es kopiert das Beispiel-Config-File falls noch keine Konfiguration existiert und warnt dass die SMTP-Einstellungen noch angepasst werden müssen. + +Das Script kann auch bestehende Konfigurationen auf Vollständigkeit prüfen - es erkennt fehlende Sektionen oder ungültige Werte und gibt entsprechende Hinweise. + +### Phase 6: System-Test durchführen +**[health-check.sh](health-check-sh.md)** versucht den furt-Service zu erreichen und seine grundlegenden Funktionen zu testen. Bei einer Fresh Installation kann dieser Test fehlschlagen weil der Service noch nicht gestartet wurde - das ist normal und erwartet. + +Das Script kann auch gegen entfernte furt-Installationen getestet werden um zu verifizieren dass Updates korrekt funktionieren. + +## Fresh vs. Upgrade Installation + +Das Orchestrator-Script `install.sh` unterstützt zwei Modi die sich in der Anzahl der ausgeführten Phasen unterscheiden: + +### Fresh Installation (Standard) +```bash +./install.sh +``` +Führt alle sechs Phasen aus. Geeignet für neue Installationen auf Systemen wo furt noch nie installiert war. + +### Upgrade Installation ```bash ./install.sh --upgrade ``` -Führt nur Schritte 2, 3 und 5 aus - überspringt Benutzer-Erstellung und Service-Installation. +Überspringt Phasen 1 und 4 (User- und Service-Erstellung) und führt nur die Phasen 2, 3, 5 und 6 aus. Geeignet für Updates bestehender furt-Installationen wo nur der Source-Code aktualisiert werden soll. -## Script-Koordination - -Die Scripts arbeiten in einer definierten Reihenfolge zusammen: - -**Phase 1 → 2:** User aus Phase 1 für Directory-Ownership -**Phase 2 → 3:** Verzeichnisse aus Phase 2 für Code-Installation -**Phase 3 → 4:** Code aus Phase 3 für Service-Templates -**Phase 4 → 5:** Service-Konfiguration validieren -**Phase 5 → 6:** Gesamtsystem testen +Der Upgrade-Modus ist erheblich schneller weil er keine System-Änderungen vornimmt. Er aktualisiert nur den Code in `/usr/local/share/furt/` und validiert dass die bestehende Konfiguration noch kompatibel ist. ## Einzelne Scripts verwenden -Jedes Script kann für Debugging oder spezielle Anwendungsfälle einzeln ausgeführt werden: +Jedes Helper Script kann auch einzeln ausgeführt werden. Das ist besonders nützlich für Debugging, spezielle Wartungsaufgaben oder wenn nur ein bestimmter Aspekt der Installation aktualisiert werden soll: ```bash -# Nur Konfiguration validieren +# Nur Source-Code aktualisieren ohne Service-Neustart +sudo ./scripts/sync-files.sh + +# Konfiguration auf Vollständigkeit prüfen sudo ./scripts/validate-config.sh -# Health-Check gegen Remote-Host -./scripts/health-check.sh --host 192.168.1.100 +# Health-Check gegen entfernten Server +./scripts/health-check.sh --host 192.168.1.100 --port 7811 -# Source-Code ohne Service-Neustart aktualisieren -sudo ./scripts/sync-files.sh +# Benutzer und Verzeichnisse für Test-Installation vorbereiten +sudo ./scripts/setup-user.sh +sudo ./scripts/setup-directories.sh ``` -## Script-Erweiterungen +Diese Flexibilität macht das Script-System zu einem nützlichen Werkzeugkasten über die reine Installation hinaus. Du kannst einzelne Scripts für Monitoring, Wartung oder Debugging verwenden. -Neue Scripts können einfach in die `scripts/`-Verzeichnis hinzugefügt und vom Orchestrator aufgerufen werden. Das System ist für Erweiterungen designt ohne die bestehende Funktionalität zu beeinträchtigen. +## Script-Fehler diagnostizieren -## Fehlerdiagnose - -Bei Script-Fehlern hilft das modulare Design bei der Lokalisierung: +Das modulare Design hilft erheblich bei der Fehlerdiagnose. Wenn die orchestrierte Installation fehlschlägt, zeigt die Ausgabe genau welches Script das Problem verursacht hat: ```bash -# Debug-Modus für einzelne Scripts -sh -x ./scripts/setup-directories.sh - -# Scripts auch bei Fehlern weiterlaufen lassen -# Temporär 'set -e' entfernen für mehr Kontext +[INFO] Phase 1: Setting up system user... OK +[INFO] Phase 2: Creating directory structure... OK +[INFO] Phase 3: Installing source code... FAILED +[ERROR] sync-files.sh: Permission denied writing to /usr/local/share/furt/ ``` -**Detaillierte Dokumentation:** Jedes der 6 Helper Scripts hat eine eigene Dokumentationsseite mit Code-Beispielen und Erweiterungsmöglichkeiten. \ No newline at end of file +Du kannst dann das spezifische Script im Debug-Modus ausführen um mehr Details zu erhalten: + +```bash +# Debug-Ausgabe für ein einzelnes Script +sh -x ./scripts/sync-files.sh +``` + +Häufige Probleme sind unzureichende Berechtigungen (Script nicht als root ausgeführt), bereits existierende Benutzer (bei Fresh Installation) oder fehlende Abhängigkeiten (Lua-Module nicht installiert). + +## Scripts erweitern und anpassen + +Das Script-System ist für Erweiterungen designt. Neue Scripts können einfach in das `scripts/`-Verzeichnis hinzugefügt und vom Orchestrator aufgerufen werden. Jedes Script folgt den gleichen Konventionen: + +- POSIX-Shell für maximale Kompatibilität +- Explizite Fehlerbehandlung mit `set -e` +- Detaillierte Statusmeldungen +- Idempotenz (mehrfache Ausführung sicher) +- Betriebssystem-Erkennung wo nötig + +Diese Konsistenz macht es einfach das System zu verstehen und zu erweitern ohne bestehende Funktionalität zu beeinträchtigen. + +Die Helper Scripts transformieren die manuelle furt-Installation von einem fehleranfälligen, wiederholenden Prozess zu einem robusten, automatisierten Workflow der bei Bedarf fein-granular gesteuert werden kann. \ No newline at end of file