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