platform-docs/adr/0024-golden-image-deployment-statt-installer-automatisierung.md

# ADR-0024: Golden-Image-Deployment statt Distributions-Installer-Automatisierung

**Status:** Beschlossen, Phase 0+1 live verifiziert
**Datum:** 29.08.2026

## Kontext

Nach einem vollen Tag Fehlersuche an Linux Mints Ubiquity-Installer (siehe
[[project_e2e_flow_dogfooding_2026-08-28]] und ADR-0023-Nachtrag) blieb
trotz eines live verifizierten, zuverlässigen AT-SPI-Autoklickers (100+
korrekte Klicks) ein tiefer, undokumentierter Blocker bestehen: Ubiquity
springt nach dem Klick auf "Jetzt installieren" wiederholt in eine
`ubiquity/partman-rebuild-cache`-Schleife zurück
(`/lib/partman/update.d/99signal_ubiquity`), ohne dass mehrere geprüfte
Hypothesen (Rezept-Flags, Timing) die Ursache klären konnten.

Diese Schwierigkeit ist strukturell dieselbe wie das frühere WLAN-Problem
mit Fedora/Anaconda: interaktive Distributions-Installer (Ubiquity,
Anaconda, potenziell Subiquity) sind für menschliche Bedienung gebaut,
nicht für Automatisierung - jede Automatisierungslösung dagegen ist eine
fragile, distributionsspezifische Sonderkonstruktion. Zusätzlich würde
"jeden Installer einzeln automatisieren" das Projekt vom eigentlichen
Ziel wegbewegen, dass ein Kunde frei zwischen Distributionen wählen kann.

Der User hat diese Einschätzung unabhängig mit einer separaten
Claude-Web-Session vertieft; nach kritischer Durchsicht dieses Gesprächs
wurde gemeinsam entschieden, die Richtung zu ändern.

## Entscheidung

Der eigentliche Installationsschritt wird durch das Muster ersetzt, das
curtin (Canonical/MAAS) und FAI (Debian) bereits lösen: das bestehende,
bereits distributionsunabhängige Boot-/Provisionierungs-Environment
(Tuxflotte-Module `00`-`40`: Hardware-Erkennung, Netzwerk/WLAN,
Registrierung, Blueprint-Abruf) partitioniert die Zielplatte direkt
(`parted`/`mkfs`), entpackt ein fertiges Root-Filesystem-Image und macht
chroot-Nacharbeiten (fstab, initramfs, machine-id, SSH-Hostkeys,
Bootloader).

**Golden Image bewusst schlank, ohne Desktop-Umgebung:** bei Tuxflotte
ist die kundensichtbare Identität (Cinnamon, Theming) laut
Blueprint/Merkmal-Modell (ADR-0002) ohnehin ein Merkmal, das der
Provisioning Agent erst nach dem ersten Boot per Ansible ausrollt - das
Golden Image selbst muss nur überall booten und Netzwerk haben. Damit
entfällt Ubiquity/GTK/AT-SPI für den Image-Bau komplett: der Bau läuft
rein über `debootstrap`, CLI-only, ohne GUI-Installer.

**Reines Debian statt Mints Ubuntu-Basis nachzubilden:** da die
kundensichtbare Identität komplett aus der Ansible-Schicht kommt, ist die
exakte Basis-Distribution des Images zweitrangig - ein Nebeneffekt ist,
dass dieselbe Debian-Basis später auch für ein mögliches Ubuntu-Angebot
wiederverwendbar wäre.

**Selbst gebaut statt curtin/FAI zu adoptieren:** die Einzelschritte
(parted/mkfs, tar/squashfs-Extraktion, chroot-Fixup, grub-install) sind
Standard-Handwerk. Volle Kontrolle/Debugbarkeit wiegt schwerer als der
Wegfall von Ubiquity/Anacondas eingebauter Bootloader-/Hardware-Logik -
genau die Fremdcode-Undurchsichtigkeit war das heutige Kernproblem.

**Architektonisch passend:** `scripts/modules/40_backend.sh` orchestriert
Backends bereits über eine Fünf-Funktionen-Lebenszyklus-Schnittstelle
(`backend_init`/`backend_validate`/`backend_generate_config`/
`backend_launch`/`backend_postinstall`) - ein neues Backend fügt sich ein,
ohne Orchestrator oder Module `00`-`40` zu ändern. Der Agent-Bootstrap
(`backends/mint/postinstall.sh`) ist bereits ein reines,
distributionsunabhängiges Bash-Skript, wiederverwendbar durch einfaches
chroot-Ausführen statt über `ubiquity/success_command`.

Die heutige Ubiquity/AT-SPI-Arbeit bleibt als dokumentierte Referenz
(ADR-0023) erhalten, hat aber keine aktive Rolle mehr in diesem Plan -
auch nicht als Image-Bau-Werkzeug.

Vollständiger Phasenplan: `~/.claude/plans/inherited-forging-puffin.md`
(Phase 0: Golden Image bauen; Phase 1: Kernmechanik isoliert testen;
Phase 2: neues Backend `backends/mint-image/`; Phase 3: End-to-End über
den echten Self-Service-Flow; Phase 4: diese ADR + Memory).

## Phase 0+1: live verifiziert (29.08.2026)

`scripts/build_golden_image.sh` baut eine schlanke Debian-bookworm-Basis
(Kernel, breites `linux-firmware`, NetworkManager, openssh-server) - kein
Root-Passwort, keine SSH-Hostkeys im Ergebnis (reale Zugangsdaten
entstehen erst durch den Provisioning Agent pro Geraet).
`scripts/lib/image_deploy.sh` kapselt die Deployment-Mechanik
(partitionieren, formatieren, mounten, Image entpacken, fstab aus echten
UUIDs, chroot-Fixup, Bootloader-Installation UEFI+BIOS) als
wiederverwendbare Funktionsbibliothek; `scripts/image_deploy_test.sh` ist
der isolierte Testtreiber für Phase 1.

Live auf der lenny-QEMU-VM getestet (frische 20-GB-Platte, UEFI/OVMF),
dabei drei reale Bugs gefunden und behoben:

1. **`zstd` verweigerte das Überschreiben** der Ausgabedatei bei
   wiederholten Baeulaeufen - `-f` ergänzt.
2. **`grub-install` konnte im Testkontext keinen NVRAM-Booteintrag
   setzen** ("EFI variables are not supported on this system"), ohne
   `--removable` blieb dann nur ein benannter Pfad übrig, den die
   Firmware ohne NVRAM-Eintrag nie findet ("No bootable option or device
   was found" beim ersten Boot-Test). Fix: zusätzlicher `grub-install`-
   Lauf mit `--removable` schreibt auf den Standard-Fallback-Pfad
   `EFI/BOOT/BOOTX64.EFI` - robuster generell für heterogene
   Zielhardware, nicht nur für dieses Testszenario.
3. **Kritischster Fund:** das komplette Root-Dateisystem des Golden
   Image hatte die Rechte `0700` statt `0755` - `mktemp -d` legt sein
   Zielverzeichnis mit `0700` an, `debootstrap` ändert das nicht, und
   `tar -p` übernahm diesen Modus beim Verpacken/Entpacken 1:1 als
   Root-Verzeichnis-Rechte des gesamten ausgerollten Systems. Ergebnis:
   jeder nicht-root-Prozess (dbus-daemon wechselt intern auf den
   unprivilegierten "messagebus"-Benutzer) bekam "Permission denied"
   schon beim Traversieren von "/" - eine komplette Boot-Fehlerkaskade
   (dbus, systemd-logind, NetworkManager, wpa_supplicant, ModemManager
   schlugen alle fehl, kein Netzwerk). Fix: `chmod 0755` direkt nach
   `debootstrap` in `build_golden_image.sh`.

Nach allen drei Fixes: sauberer, stiller Boot bis zum Login-Prompt, keine
einzige `[FAILED]`-Zeile, echte DHCP-Lease bestätigt
(`192.168.122.244`, Hostname `tuxflotte-image-test` korrekt gesetzt). Der
Erfolgsmaßstab für Phase 0+1 ("bootet überall, hat Netzwerk") ist damit
erreicht.

## Nachtrag (30.08.2026): Debian trixie statt bookworm, erweiterte WLAN-Abdeckung, Umzug auf enterprise

Nach Rückfrage des Users umgestellt:

- **`trixie` (Debian 13) statt `bookworm`** als Ziel-Suite - bookworm ist
  inzwischen oldstable, trixie liefert ausserdem von Haus aus einen
  neueren Kernel (6.12 statt 6.1), direkt relevant fürs Ziel "möglichst
  breite Hardwareunterstützung". Die Secure-Boot-Kette
  (`shim-signed`/`grub-efi-amd64-signed`/signierter Kernel) funktioniert
  in beiden Suiten identisch - kein Unterschied dort, DKMS-Module
  (Nvidia u.ä.) bleiben so oder so unsigniert und damit Agent-Zuständigkeit.
- **WLAN-Paketliste erweitert:** `firmware-brcm80211` (Broadcom, vorher
  nicht abgedeckt), `wireless-regdb` (Regulatory-Datenbank - ohne sie
  Kanal-/Sendeleistungs-Einschränkungen, leicht zu übersehen),
  `wpasupplicant` explizit (kam vorher nur transitiv mit), `iw` + `rfkill`
  (Diagnose/Kontrolle).
- **Testinfrastruktur von lenny auf enterprise umgezogen:** enterprise ist
  eine Workstation mit praktischer 24/7-Verfügbarkeit, lenny ein Notebook
  auf WLAN, das reist und einschläft - für mehrstündige/mehrstufige
  Testzyklen unzuverlässiger. Dieselbe VM (`tuxflotte-mint-autoinstall-test`,
  vormals eine andere Testfixtur auf enterprise, siehe
  [[project_qemu_vm_enterprise]]) wurde auf UEFI/OVMF umgestellt und für
  diesen Zweck wiederverwendet.

**Erneut live verifiziert (trixie + erweiterte WLAN-Pakete, auf enterprise):**
sauberer Boot ("Debian GNU/Linux 13"), keine `[FAILED]`-Zeile, bestätigte
DHCP-Lease. Image-Größe rund 448 MB (etwas größer als die bookworm-Fassung
durch neuere/mehr Pakete).

## Nächste Schritte

Phase 2 (Backend `backends/mint-image/`) und Phase 3 (End-to-End über den
echten Self-Service-Flow) sind noch offen - siehe Plandatei. Fedora/Ubuntu
folgen erst nach erfolgreichem Mint-Vollzyklus demselben Muster.