Initial commit: macOS USB Stick Creator - Docker Compose Web-GUI fuer bootfaehige macOS-Installer

README.md

@@ -0,0 +1,86 @@
+# macOS USB Installer Tool
+
+Lokale Web-GUI (Docker Compose) die macOS-Installer direkt von Apples
+Servern laedt und einen bootfaehigen USB-Stick daraus baut — ohne Mac.
+
+## Start
+
+```bash
+docker compose up --build
+```
+
+Dann im Browser: **http://127.0.0.1:8080**
+
+Der Port bindet bewusst NUR an `127.0.0.1` (nicht `0.0.0.0`) — von aussen
+im Netzwerk nicht erreichbar.
+
+## Wie es funktioniert
+
+### 1. Versions-Liste (automatisch aktuell)
+Beim Container-Start wird gegen Apples echten Software-Update-Katalog
+(`swscan.apple.com`) geprobt, welche macOS-Installer aktuell verfuegbar
+sind. Das Namensschema der Katalog-URLs ist bekannt und wurde live
+verifiziert (Stand: Erstellung dieses Tools). Wenn Apple eine neue
+macOS-Hauptversion veroeffentlicht, taucht sie **automatisch beim naechsten
+Container-Start** in der Liste auf — ohne Code-Aenderung, solange Apple
+das Namensschema beibehaelt (das ist seit vielen Jahren stabil, aber keine
+100%-Garantie fuer alle Zeit).
+
+Per "neu laden"-Button in der GUI kann der Katalog auch ohne Neustart
+aktualisiert werden.
+
+### 2. Zwei Installations-Pfade
+
+| macOS-Version | Pfad | Status |
+|---|---|---|
+| bis Catalina (10.15) | `legacy_dmg`: BaseSystem.dmg direkt per `dd` auf den Stick | **robust, gut etabliert** |
+| ab Big Sur (11) aufwaerts | `recovery`: `InstallAssistant.pkg` wird entpackt (`xar` → `pbzx` → `cpio`), das darin enthaltene `SharedSupport.dmg`/`BaseSystem.dmg` wird dann per `dd` geschrieben | **experimentell** |
+
+**Warum der Unterschied:** Ab macOS Big Sur liefert Apple keinen fertigen
+Installer-Datentraeger mehr, sondern ein Programm-Paket. Das eigentliche
+Tool das daraus einen vollstaendigen Multi-Volume-Installer-Stick baut
+(`createinstallmedia`) laeuft nur unter echtem macOS. Dieses Tool geht
+stattdessen den Community-erprobten Weg: das darin enthaltene
+Recovery-/BaseSystem-Image direkt extrahieren und schreiben. Der Stick
+bootet damit in ein Internet-Recovery-System, das den Rest der
+Installation von Apples Servern nachlaedt.
+
+**Das ist der fragilste Teil des ganzen Tools.** Apple hat den internen
+Aufbau von `InstallAssistant.pkg` in der Vergangenheit leicht veraendert.
+Wenn die Extraktion fehlschlaegt (Fehlermeldung im Log-Fenster), ist das
+kein Bug im eigentlichen Sinn, sondern ein Zeichen dass sich intern was
+geaendert hat — dann muss `backend/installer.py` (`_extract_recovery_dmg`)
+angepasst werden.
+
+### 3. USB-Geraete-Erkennung
+Der Container laeuft mit `privileged: true` und mountet `/dev` sowie
+`/run/udev` vom Host durch — noetig, um Sticks direkt zu partitionieren
+und zu beschreiben. Das ist bewusst so gebaut, bedeutet aber: der Container
+hat vollen Zugriff auf **alle** Block-Devices des Rechners. Deshalb:
+
+- Port ist NUR auf `127.0.0.1` gebunden (kein Netzwerk-Zugriff von aussen).
+- Die System-Platte (auf der `/` liegt) wird automatisch als Ziel gesperrt.
+- Nur Geraete mit USB-Transport werden als Ziel akzeptiert.
+- Vor dem Schreiben muss der exakte Geraetepfad (z.B. `/dev/sdb`) nochmal
+  von Hand eingetippt werden — kein versehentliches Ein-Klick-Loeschen.
+
+**Trotzdem gilt:** das Tool schreibt mit `dd` und `wipefs` direkt auf ein
+Block-Device. Wenn du das falsche Geraet auswaehlst, sind die Daten weg.
+Vor dem Start immer pruefen, welcher Stick tatsaechlich gemeint ist (Groesse
+und Modell in der GUI vergleichen).
+
+## Voraussetzungen auf dem Host
+- Docker + Docker Compose
+- Linux (getestet gegen die Grundannahmen von `lsblk`/`/dev`/`udev`; auf
+  macOS/Windows-Docker-Desktop funktioniert das Device-Passthrough so nicht)
+
+## Bekannte Grenzen (ehrlich, nicht schoengeredet)
+1. Der `recovery`-Pfad (Big Sur+) ist nicht production-hardened getestet
+   worden, sondern nach dokumentiertem, in der Hackintosh-/Recovery-Community
+   etabliertem Verfahren gebaut. Rechne bei sehr neuen macOS-Versionen mit
+   Nacharbeit.
+2. Die Katalog-Zukunftssicherheit haengt an Apples URL-Namensschema. Bricht
+   Apple das Schema, muss `backend/catalog.py` angepasst werden (kurzer Fix,
+   kein Rewrite).
+3. Kein Windows/macOS-Docker-Host-Support fuer das Device-Passthrough —
+   nur natives Linux.