222 lines
6.9 KiB
Markdown
222 lines
6.9 KiB
Markdown
# 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**
|
|
|