From cfdf4aea4fc7504647dd43f0d4802d811be633d0 Mon Sep 17 00:00:00 2001 From: michael Date: Mon, 8 Sep 2025 19:08:28 +0200 Subject: [PATCH] =?UTF-8?q?Installation=20automatisiert=20hinzugef=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Installation-automatisiert.md | 188 ++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 Installation-automatisiert.md diff --git a/Installation-automatisiert.md b/Installation-automatisiert.md new file mode 100644 index 0000000..a8abc0e --- /dev/null +++ b/Installation-automatisiert.md @@ -0,0 +1,188 @@ +# Installation automatisiert + +**Helper Scripts für wiederkehrende furt-Installationen** + +## Getestet unter +- OpenBSD 7.7 +- Debian 12 +- Arch Linux + +## Automatisierung verstehen + +Nach mehreren manuellen furt-Installationen entstand ein Set von Helper Scripts die den Installationsprozess automatisieren. Diese Scripts kapseln die manuellen Schritte aus der Standard-Installation und machen sie wiederholbar. Jedes Script übernimmt einen spezifischen Teil der Installation und kann bei Bedarf auch einzeln ausgeführt werden. + +Der zentrale Orchestrator `install.sh` ruft sechs spezialisierte Scripts in der korrekten Reihenfolge auf. Diese modulare Struktur ermöglicht es Teile der Installation zu überspringen oder nur bestimmte Komponenten zu aktualisieren. + +## Voraussetzungen prüfen + +Die Helper Scripts setzen voraus dass Lua 5.1 und die benötigten Module bereits installiert sind. Diese Abhängigkeiten können die Scripts nicht automatisch installieren da jede Distribution andere Paketnamen verwendet: + +```bash +# OpenBSD +doas pkg_add lua lua-socket lua-cjson luasec + +# Debian +sudo apt install lua5.1 lua-socket lua-cjson lua-sec + +# Arch Linux +sudo pacman -S lua51 lua51-socket lua51-dkjson lua51-sec +``` + +Die Scripts prüfen während der Installation ob alle Module verfügbar sind und geben entsprechende Fehlermeldungen aus. + +## Source-Code beschaffen + +Für die automatisierte Installation benötigst du das komplette furt-Package inklusive aller Helper Scripts: + +```bash +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 +``` + +Das Package enthält die komplette `scripts/`-Verzeichnisstruktur mit allen Helper Scripts und den plattformspezifischen Service-Templates im `deployment/`-Verzeichnis. + +## Fresh Installation + +Für eine neue furt-Installation führst du einfach das Orchestrator-Script aus: + +```bash +# OpenBSD +doas ./install.sh + +# Linux +sudo ./install.sh +``` + +Das Script durchläuft sechs Phasen und gibt für jeden Schritt eine Statusmeldung aus: + +**Phase 1 - System-Benutzer erstellen:** Das `setup-user.sh` Script erkennt automatisch das Betriebssystem und erstellt den entsprechenden System-Benutzer. Unter OpenBSD wird `_furt` angelegt, unter Linux `furt` mit dem `--system` Flag. + +**Phase 2 - Verzeichnisse einrichten:** Das `setup-directories.sh` Script erstellt die komplette Verzeichnisstruktur mit korrekten Berechtigungen. Es erkennt automatisch ob Config-Dateien nach `/usr/local/etc/furt/` (BSD) oder `/etc/furt/` (Linux) gehören. + +**Phase 3 - Source-Code synchronisieren:** Das `sync-files.sh` Script kopiert alle Source-Verzeichnisse nach `/usr/local/share/furt/` und setzt die korrekten Berechtigungen. Version-Dateien für die merkwerk-Integration werden automatisch mit kopiert falls vorhanden. + +**Phase 4 - Service integrieren:** Das `create-service.sh` Script installiert die passenden Service-Templates aus dem `deployment/`-Verzeichnis. Unter OpenBSD wird das rc.d-Script nach `/etc/rc.d/furt` kopiert und mit `rcctl enable` aktiviert. Unter Linux wird die systemd-Unit installiert und mit `systemctl enable` aktiviert. + +**Phase 5 - Konfiguration validieren:** Das `validate-config.sh` Script prüft ob eine gültige Konfigurationsdatei vorhanden ist. Da noch keine produktive Konfiguration existiert, gibt es eine Warnung aus dass die Beispiel-Konfiguration noch angepasst werden muss. + +**Phase 6 - Health Check:** Das `health-check.sh` Script versucht den Service zu erreichen. Bei einer Fresh Installation schlägt dies erwartungsgemäß fehl da der Service noch nicht gestartet wurde. + +Nach erfolgreicher Installation zeigt das Script eine Zusammenfassung mit den nächsten Schritten: + +``` +=== Installation Summary === +furt installation completed successfully + +Next steps: +1. Edit configuration file: /usr/local/etc/furt/furt.conf +2. Start the service: doas rcctl start furt +3. Test the API: curl http://127.0.0.1:7811/health +``` + +## Konfiguration anpassen + +Die Helper Scripts kopieren automatisch das Beispiel-Config-File, du musst es aber noch an deine Umgebung anpassen: + +```bash +# OpenBSD +doas $EDITOR /usr/local/etc/furt/furt.conf + +# Linux +sudo $EDITOR /etc/furt/furt.conf +``` + +Die wichtigsten Anpassungen sind SMTP-Zugangsdaten und API-Keys. Das Config-Format ist identisch zur manuellen Installation. + +## Service starten + +Nach der Konfiguration startest du furt mit den Standard-System-Tools: + +```bash +# OpenBSD +doas rcctl start furt +doas rcctl check furt + +# Linux +sudo systemctl start furt +sudo systemctl status furt +``` + +Die Helper Scripts haben den Service bereits für automatischen Start beim Booten konfiguriert. + +## Upgrade-Installation + +Für Updates existierender furt-Installationen nutzt du den Upgrade-Modus. Dieser überspringt die Benutzer- und Service-Erstellung und aktualisiert nur den Source-Code: + +```bash +# Neues Package herunterladen +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 + +# Upgrade durchführen +doas ./install.sh --upgrade # OpenBSD +sudo ./install.sh --upgrade # Linux +``` + +Der Upgrade-Modus führt nur drei Schritte aus: + +**Verzeichnisse prüfen:** Stellt sicher dass die Ziel-Verzeichnisse existieren, erstellt aber keine neuen Benutzer oder Services. + +**Source-Code aktualisieren:** Überschreibt den kompletten Inhalt von `/usr/local/share/furt/` mit der neuen Version. Die Konfiguration in `/usr/local/etc/furt/` oder `/etc/furt/` bleibt unverändert. + +**Validation:** Prüft dass die neue Version korrekt installiert wurde und die bestehende Konfiguration noch gültig ist. + +Nach einem Upgrade zeigt das Script die neue Versionsnummer und erinnert daran den Service neu zu starten: + +``` +=== Installation Summary === +furt upgrade completed successfully + +Source code updated to: + Version: 0.1.2+abc123 + +Service restart required: + doas rcctl restart furt +``` + +## Git-basierte Updates + +Wenn du furt aus dem Git-Repository installiert hast, kannst du Updates direkt über Git beziehen: + +```bash +cd /pfad/zu/furt-source +git pull +doas ./install.sh --upgrade +doas rcctl restart furt # OpenBSD +sudo systemctl restart furt # Linux +``` + +Diese Methode ist besonders für Entwicklungsumgebungen geeignet wo du die neuesten Änderungen testen möchtest. + +## Einzelne Scripts ausführen + +Jedes Helper Script kann auch einzeln ausgeführt werden. Dies ist nützlich für Debugging oder wenn du nur bestimmte Teile der Installation aktualisieren möchtest: + +```bash +# Nur Source-Code aktualisieren +sudo ./scripts/sync-files.sh + +# Nur Konfiguration validieren +sudo ./scripts/validate-config.sh + +# Nur Health Check +./scripts/health-check.sh +``` + +Die Scripts prüfen ihre Voraussetzungen und geben entsprechende Fehlermeldungen aus wenn Abhängigkeiten fehlen. + +## Installationsfehler diagnostizieren + +Bei Problemen während der automatisierten Installation hilft die modulare Struktur bei der Fehlersuche. Jedes Script gibt detaillierte Statusmeldungen aus und bricht bei Fehlern ab. + +Häufige Probleme sind fehlende Berechtigungen, bereits existierende Benutzer oder unvollständige Package-Downloads. Die Scripts geben spezifische Fehlermeldungen aus die auf das Problem hinweisen. + +Bei komplexeren Problemen kannst du zur manuellen Installation zurückkehren um jeden Schritt einzeln zu kontrollieren und zu verstehen wo der Fehler auftritt. + +Die automatisierte Installation beschleunigt wiederkehrende furt-Deployments erheblich und reduziert die Wahrscheinlichkeit von Tippfehlern bei der manuellen Installation. \ No newline at end of file