installerscript-sh/Cookbook.md

Homelab Installer Cookbook (Vollversion)

Dieses Dokument dient als zentrale Wissensbasis für die Entwicklung, Erweiterung und Wartung des Homelab Installationssystems. Es ermöglicht zukünftigen Sessions sofort einzusteigen, ohne Kontext erneut aufzubauen.

---

1. Projektüberblick

Das Ziel des Systems ist die automatisierte Einrichtung von Servern im Homelab mittels wiederverwendbarer und modularer Installationsrezepte.

Anforderungen

• Keine externen Tools außer Bash + optional Ansible
• Kein Git notwendig
• Server lädt Installationsdefinitionen dynamisch von einem Webserver
• Vollständig menügeführt, interaktiv, ohne Vorwissen
• Wiederholbare und stabile Installationen

High-Level Ablauf

install.sh (läuft lokal)
   ↓ Lädt Kategorien + Rezepte vom API-Endpoint
   ↓ Benutzer wählt Kategorie und Rezept
   ↓ Rezept enthält entweder install.sh (Shell) oder playbook.yml (Ansible)
   ↓ Rezept wird ausgeführt

---

2. Webserver-Struktur

Auf dem Webserver liegt alles, was der Installer benötigt:

public_html/
 ├─ info.php                → liefert JSON Index der verfügbaren Rezepte
 └─ recipes/                → enthält Rezepte (Modularblöcke)
     ├─ system/             → Systemnahe Dinge (z.B. base-system, docker)
     ├─ services/           → Einzeldienste (z.B. ollama, open-webui)
     └─ stacks/             → zusammengesetzte Sets aus mehreren Services

---

3. Lokale Struktur auf dem Zielsystem

/opt/homelab/playbooks/        → gespeicherte Playbooks
/srv/docker/                    → Zielort für alle Docker-Container
/tmp/homelab-installer/         → temporäre Downloads
/var/log/homelab-installer.log  → Installer Logfile

---

4. Rezepte

Jedes Rezept kann eine oder beide Varianten enthalten:

Datei	Bedeutung
install.sh	Shell-Installation (prozedural)
playbook.yml	Ansible Installation (deklarativ, idempotent)

Der Installer erkennt automatisch:

• Nur Shell → Shell-Modus
• Nur Playbook → Ansible-Modus
• Beide → Benutzer darf wählen

4.1 Gemeinsame Basisfunktionen für Shell-Rezepte

Alle Shell-Rezepte können folgende Funktionen voraussetzen, die vom Haupt-Installer bereitgestellt werden:

Funktion	Zweck
ensure_root	Stellt sicher, dass Befehle mit Root-Rechten ausgeführt werden (direkt oder über sudo).
detect_pkg_manager	Erkennt automatisch ob apt, dnf, pacman oder apk verwendet wird.
pkg_install <pakete...>	Installiert Pakete unabhängig vom Paketmanager (inkl. apt update bei Bedarf).
install_docker	Installiert Docker und Docker Compose Plugin, falls noch nicht vorhanden.
ask_to_install "NAME"	Fragt den Benutzer, ob ein bestimmtes Element installiert werden soll (J/n, Default J).
begin_password_section "NAME"	Startet einen Passwortblock in der zentralen Schlüsseldatei.
generate_password "variablen_name"	Erzeugt ein starkes Passwort und speichert es automatisch in keys.txt.
end_password_section "NAME"	Schließt den Passwortblock wieder ab.

Shell-Rezepte dürfen keine eigene Root-Abfrage, sudo-Logik oder Paketmanager-Abfragen enthalten. Diese Logik liegt zentral im Haupt-Installer.

---

5. Shell-Recipe Style Guide (aktualisiert)

Shell-Rezepte sollen:

• immer mit #!/usr/bin/env bash beginnen
• set -euo pipefail für robustes Fehlerverhalten verwenden
• keine direkten apt, dnf, pacman, apk, sudo, docker Befehle enthalten
• statt dessen ensure_root, detect_pkg_manager, $SUDO, pkg_install, install_docker, ask_to_install verwenden
• falls Passwörter benötigt werden, diese mit generate_password erzeugen
• Passwörter immer in einem benannten Block speichern, damit die zentrale keys.txt später lesbar bleibt

Minimalbeispiel

#!/usr/bin/env bash
set -euo pipefail

ensure_root
detect_pkg_manager

begin_password_section "OLLAMA"
ADMIN_PASS="$(generate_password "ollama_admin")"
end_password_section "OLLAMA"

pkg_install curl gnupg lsb-release

$SUDO mkdir -p /srv/docker/ollama
cd /srv/docker/ollama

$SUDO tee docker-compose.yml >/dev/null <<EOF
services:
  ollama:
    image: ollama/ollama:latest
EOF

$SUDO docker compose up -d

log "OLLAMA wurde erfolgreich installiert."

---

6. Ansible Playbook Style Guide

• Jede Aufgabe muss wiederholbar sein
• Keine Raw-Shell-Kommandos, wenn es ein Modul gibt
• Immer become: true
• Lokaler Modus: ansible-playbook -i localhost, …

---

7. Stacks

Ein Stack ist einfach ein Shell- oder YAML-Script, das mehrere Recipes hintereinander ausführt.

---

8. Neues Rezept hinzufügen

1. Wähle Kategorie (system, services, stacks)
2. Erstelle neuen Ordner innen: recipes/<kategorie>/<name>/
3. Lege install.sh oder playbook.yml ab
4. Rezepte verwenden ab jetzt immer ensure_root, detect_pkg_manager, pkg_install

8.1 Passwort-Handling Standard

Wenn Rezepte Zugangsdaten erzeugen, werden sie automatisch in einer Datei gespeichert:

keys.txt
(im Verzeichnis, in dem der Haupt-Installer ausgeführt wurde)

Format:

===== REZEPTNAME =====
schluessel_name = wert
...
===== ENDE REZEPTNAME =====

Beispiel für ein Rezept namens ollama:

===== OLLAMA =====
ollama_admin = Gs92hs7shs8192hsbs8==
===== ENDE OLLAMA =====

Dies ermöglicht es, viele Installationen durchzuführen, ohne später den Überblick zu verlieren.

---

9. Namensregeln

Element	Regel
Ordnernamen	nur a-z0-9-
Shell Skripte	immer install.sh
Playbooks	immer playbook.yml
Keine Leerzeichen	sonst Menü kaputt

---

10. Troubleshooting

Problem	Lösung
"Installer findet Rezepte nicht"	info.php prüfen / Webserver Schreibrechte
Playbook hängt bei apt	dpkg --configure -a ausführen
Shell-Skript bricht ohne Meldung ab	set -x debug aktivieren

---

11. Roadmap

• Docker Playbook erstellen
• KI-Stack bauen (Ollama + Open-WebUI + Embeddings)
• Optional Identity-Stack (Authelia + Traefik)

---

12. Nächster Schritt

Weiter mit: docker ansible bitte