# 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

```bash
#!/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**