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

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).

Build-Hinweis (hfsprogs / xar)

hfsprogs liegt in Debians non-free-Bereich (Dockerfile aktiviert das gezielt ueber eine eigene sources.list.d-Datei), xar gibt es in bookworm ueberhaupt nicht als Paket — das wird deshalb aus dem Upstream-Repo (mackyle/xar, selber Maintainer wie das schon genutzte pbzx) selbst gebaut. Macht den ersten Build minimal langsamer, aber zuverlaessiger als ein Distro-Wechsel.

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.