Initial template repo

docs/PODMAN_DISTROBOX.md

@@ -0,0 +1,376 @@
+# Podman & Distrobox - Container auf NixOS
+
+Anleitung zur Nutzung von Podman und Distrobox für Container-Workloads.
+
+---
+
+## Was ist Podman?
+
+**Podman** = Daemonless Container Runtime (Docker-Ersatz)
+
+```
+Docker = Client-Server Architektur
+Podman = Direkt auf deinem User-Account
+```
+
+**Vorteile:**
+- ✅ Kein Root-Daemon nötig
+- ✅ Sicherer (läuft als normaler User)
+- ✅ Docker-kompatibel (`docker` CLI funktioniert)
+- ✅ Leichter als Docker
+- ✅ Perfekt für Einzelnutzer
+
+---
+
+## Was ist Distrobox?
+
+**Distrobox** = Einfache Linux-Container (für Nicht-Gaming)
+
+```
+Podman = Low-Level Container-Runtime
+Distrobox = High-Level Container Management
+```
+
+**Use Case:**
+- Du brauchst Ubuntu-Pakete, aber nutzt NixOS
+- Python/Node.js Development-Umgebung
+- Spezielle Tools die nur in anderen Distros verfügbar sind
+- Sandbox für unbekannte Software
+
+**Nicht für Gaming!** (GameMode/Steam brauchen Bare Metal)
+
+---
+
+## Aktivieren
+
+### In `configuration.nix` einfügen
+
+```nix
+imports = [
+  ./modules/containers/podman-distrobox.nix
+];
+```
+
+### Rebuild
+
+```bash
+sudo nixos-rebuild switch --flake .#template
+```
+
+---
+
+## Podman Basics
+
+### Docker-Kompatibilität
+
+Nach Aktivierung funktioniert `docker`-CLI:
+
+```bash
+# Diese Befehle funktionieren:
+docker ps
+docker run ubuntu:latest echo "Hello"
+docker pull alpine
+docker exec
+docker build
+
+# Im Hintergrund: Podman
+```
+
+### Container als User starten
+
+```bash
+# Kein sudo nötig!
+podman run -it ubuntu:latest bash
+
+# Oder
+docker run -it alpine:latest sh
+```
+
+---
+
+## Distrobox Basics
+
+### Distrobox-Container erstellen
+
+```bash
+# Ubuntu-Container
+distrobox create --name ubuntu-dev --image ubuntu:latest
+
+# Alpine-Container
+distrobox create --name alpine-work --image alpine:latest
+
+# Fedora-Container
+distrobox create --name fedora --image fedora:latest
+```
+
+### Container betreten
+
+```bash
+distrobox enter ubuntu-dev
+# Du bist jetzt in: Ubuntu Bash
+
+apt update && apt install python3
+# Ubuntu-Pakete installieren
+
+exit
+# Zurück zu NixOS
+```
+
+### Container auflisten
+
+```bash
+distrobox list
+
+# Output:
+# NAME         | STATUS       | IMAGE NAME
+# ubuntu-dev   | CREATED      | ubuntu:latest
+# alpine-work  | EXITED       | alpine:latest
+```
+
+### Container löschen
+
+```bash
+distrobox rm ubuntu-dev
+```
+
+---
+
+## Praktische Beispiele
+
+### Beispiel 1: Python Development mit Ubuntu Libs
+
+```bash
+# Container erstellen
+distrobox create --name python-dev --image ubuntu:latest
+
+# Betreten
+distrobox enter python-dev
+
+# Ubuntu-Packages installieren
+apt update && apt install -y python3-pip libpython3-dev
+pip install numpy scipy pandas
+
+# Work machen
+python3 script.py
+
+exit
+```
+
+### Beispiel 2: Node.js in Alpine
+
+```bash
+distrobox create --name nodejs --image node:18-alpine
+
+distrobox enter nodejs
+
+npm install -g yarn pnpm
+npm run dev
+
+exit
+```
+
+### Beispiel 3: Spezielle Tools (z.B. Ubuntu-Spezific)
+
+```bash
+distrobox create --name ubuntu-tools --image ubuntu:latest
+
+distrobox enter ubuntu-tools
+
+# Ubuntu-spezifische Tools installieren
+apt install -y snap  # oder andere Ubuntu-only Tools
+
+exit
+```
+
+---
+
+## Heim-Verzeichnis Zugriff
+
+Distrobox automatische Mounts:
+
+```bash
+# Von NixOS:
+echo "test" > ~/test.txt
+
+# Im Container:
+distrobox enter ubuntu-dev
+ls ~  # Zeigt ~/test.txt (selbes Verzeichnis!)
+```
+
+**Wichtig:** Dateien sind Heim-verzeichnis-übergreifend sichtbar!
+
+---
+
+## Netzwerk im Container
+
+### Zugriff auf Host
+
+```bash
+distrobox enter ubuntu-dev
+
+# Kann auf deinen Host zugreifen
+curl http://localhost:8080  # Wenn Host-Service läuft
+ping 8.8.8.8  # Internet funktioniert
+```
+
+### Container veröffentlichen
+
+```bash
+# Container als Service:
+docker run -d -p 8080:80 nginx
+
+# Dann von außen:
+curl http://localhost:8080
+```
+
+---
+
+## Performance
+
+### Podman vs. Docker
+
+```
+Docker: 100%
+Podman: 99-101% (kaum Unterschied)
+```
+
+Podman ist manchmal sogar schneller!
+
+### Distrobox Overhead
+
+```
+Native NixOS: 100%
+Im Distrobox: 98-99% (minimal)
+```
+
+Distrobox ist fast keine Verlangsamung.
+
+---
+
+## Tipps & Tricks
+
+### Persistent Storage
+
+```bash
+# Container mit Volume
+distrobox create --name work --image ubuntu:latest \
+  --volume /home/user/projects:/mnt/projects
+
+distrobox enter work
+ls /mnt/projects  # Deine Projekte!
+```
+
+### Container-Shell in NixOS starten
+
+```bash
+# Shortcut für häufig benutzte Container
+alias ubuntu-dev="distrobox enter ubuntu-dev"
+
+ubuntu-dev  # Schnell drin!
+```
+
+### Distrobox "Export" (Advanced)
+
+```bash
+# Programm aus Container in Host-Desktop sichtbar machen
+distrobox export --app APPNAME --bin /usr/bin/program
+```
+
+---
+
+## Troubleshooting
+
+### Problem: "podman: command not found"
+
+```bash
+# Überprüfe ob aktiviert:
+grep -r "podman" /etc/nixos/configuration.nix
+
+# Falls nicht: Zu configuration.nix hinzufügen
+imports = [ ./modules/containers/podman-distrobox.nix ];
+
+sudo nixos-rebuild switch --flake .#template
+```
+
+### Problem: Container haben kein Internet
+
+```bash
+# DNS prüfen
+podman run alpine ping 8.8.8.8
+
+# Fallback: DNS manuell setzen
+podman run --dns=8.8.8.8 alpine ping 8.8.8.8
+
+# Oder in Datei konfigurieren
+~/.config/containers/containers.conf:
+dns_servers = ["8.8.8.8", "1.1.1.1"]
+```
+
+### Problem: Docker alias funktioniert nicht
+
+```bash
+# Überprüfe Podman-Docker Compat:
+ls -la /run/podman/podman.sock
+
+# Falls nicht da: Neustart
+systemctl --user restart podman
+
+# Oder in nix.conf:
+environment.variables.DOCKER_HOST = "unix:///run/podman/podman.sock";
+```
+
+### Problem: "Too many open files"
+
+```bash
+# File descriptors erhöhen in gaming-tweaks.nix
+# Oder manuell:
+ulimit -n 524288
+```
+
+---
+
+## Für Freunde: Erklärung
+
+### Einfach
+
+```
+Podman = Docker für NixOS
+Distrobox = Einfache Linux-Umgebung in Container
+
+Nutzen wenn:
+- Du brauchst Ubuntu-Pakete
+- Python/Node.js Environment
+- Isolierte Software-Testing
+```
+
+### NICHT für Gaming!
+
+```
+❌ Spiele laufen nicht in Distrobox
+❌ GameMode funktioniert nicht im Container
+❌ GPU-Zugriff kompliziert
+
+✅ Nutze Bare Metal für Gaming
+```
+
+---
+
+## Checkliste
+
+- [ ] Modul in `configuration.nix` importiert
+- [ ] Rebuild durchgeführt
+- [ ] `podman run alpine echo "test"` funktioniert
+- [ ] `distrobox` Befehl verfügbar
+- [ ] Container erstellt & betreten funktioniert
+
+---
+
+## Weitere Ressourcen
+
+- Podman Docs: https://docs.podman.io/
+- Distrobox GitHub: https://github.com/89luca89/distrobox
+- OCI Images: https://hub.docker.com/ (auch mit Podman nutzbar)
+
+---
+
+**Podman ist dein neuer Docker-Ersatz auf NixOS!** 🐳→📦