Initial upload
This commit is contained in:
221
Cookbook.md
Normal file
221
Cookbook.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 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**
|
||||
|
||||
Reference in New Issue
Block a user