# Technische Beschreibung: Multi-Stage Docker Build für GPU-fähige PyTorch-Umgebungen

## Zielsetzung
Der Ansatz ermöglicht ein Docker-Image, das GPU-beschleunigte Frameworks (PyTorch + CUDA + Torchaudio) enthält, dabei jedoch kompakt bleibt, ohne Runtime-Downloads auskommt und reproduzierbar gebaut werden kann.

---

## 1. Grundprinzip

### Stage 1 – Build-/Dependency Stage
- CUDA-fähiges Base-Image (z. B. `nvidia/cuda:12.1.0-runtime-ubuntu22.04`)
- Installation schwerer Abhängigkeiten:
  - `torch` (CUDA-Build)
  - `torchaudio`
- Enthält alle Build-Tools und Systemdependencies
- Ergebnis: vollständiges GPU-fähiges `site-packages`

### Stage 2 – Runtime Stage
- Leichtes Slim-Python-Image (z. B. `python:3.11-slim`)
- Nur das fertige `site-packages` aus Stage 1 wird kopiert
- Keine Build-Kette, keine Compiler, keine großen Pakete

---

## 2. Vorteile gegenüber anderen Ansätzen

### Gegenüber Single-Stage Builds
| Problem | Multi-Stage Lösung |
|--------|---------------------|
| Finales Image wird 5–10 GB groß | Nur Runtime-Layer → deutlich kleiner |
| Komplexer Build im finalen Image | Build isoliert in Stage 1 |
| Sicherheitsrisiken | Minimale Angriffsfläche im Runtime-Image |

### Gegenüber Runtime-Installation (EntryPoint)
| Runtime-Install | Multi-Stage |
|------------------|-------------|
| Lange Startup-Zeit | Installation beim Build |
| Internetzugang nötig | Runtime benötigt kein Netzwerk |
| Nicht deterministisch | Reproduzierbare Builds |

---

## 3. Technischer Ablauf im Detail

### Stage 1: Builder
- CUDA-fähiges Image
- Installation aller Dependencies inkl. Torch + CUDA
- Resultierendes `site-packages` wird vorbereitet

### Stage 2: Runtime
- Schlankes Python-Image
- Kopieren der vorbereiteten Pakete aus Stage 1
- Hinzufügen der Anwendung
- Setzen des Entrypoints

**Host-Anforderungen:**  
- NVIDIA Treiber  
- NVIDIA Container Toolkit  
- Start mit `--gpus all`

---

## 4. CI/CD Eignung
- Deterministische Builds
- Weniger Storage
- Schnelleres Deployment
- Keine externen Abhängigkeiten bei Runtime
- Ideal für Kubernetes, GitLab CI, GitHub Actions, ArgoCD

---

## 5. Risiken & Mitigation

| Risiko | Mitigation |
|--------|------------|
| CUDA-Version mismatch | Versionen pinnen & Kompatibilitätsmatrix nutzen |
| GPU nicht verfügbar | CPU-Fallback implementieren |
| Torch-Wheel entfernt | internes Wheel-Repository verwenden |

---

## 6. TL;DR
Multi-Stage Build =  
**Torch/CUDA in eigener Build-Stage installieren → fertige Pakete in ein leichtes Runtime-Image kopieren → kleines, GPU-fähiges, sauberes Deployment.**