qt6-migration-pipeline/scripts/README-gui-docker.md

Remote X11 Docker Forwarding for Qt6 Pipeline

Diese Skripte automatisieren das Durchreichen von grafischen Anwendungen (GUI) aus einem Docker-Container über eine SSH-Verbindung innerhalb einer GNU screen-Session. Sie lösen die typischen Probleme mit X11-Cookies (.Xauthority) und wechselnden Display-Nummern.

🚀 Voraussetzungen

1. Lokal: Ein laufender X-Server (Linux Desktop, XQuartz auf macOS oder VcXsrv/Xming auf Windows).
2. SSH-Verbindung: Verbindung zum Server zwingend mit X11-Weiterleitung aufbauen:

   ssh -Y torsten@greifserv
   

3. In Screen: Stelle vor dem Start sicher, dass $DISPLAY in deiner Shell gesetzt ist (z. B. export DISPLAY=localhost:10.0).

---

🛠️ Verwendung der Skripte

Beide Skripte müssen vor der ersten Nutzung ausführbar gemacht werden:

chmod +x run_gui_docker.sh exec_gui_docker.sh

1. Container neu starten (run_gui_docker.sh)

Extrahiert das X11-Sicherheits-Cookie des Host-Users, bereinigt Hostnamen-Konflikte, startet den Container im Host-Netzwerk (--net=host) und konfiguriert die Rechte im Container vollautomatisch.

• Ausführung:

  ./run_gui_docker.sh
  

• Test im Container: xclock & eingeben. Die Uhr sollte auf deinem lokalen PC erscheinen.

2. In laufenden Container einklinken (exec_gui_docker.sh)

Öffnet eine weitere Shell (neues Screen-Fenster/Tab) in dem bereits laufenden GUI-Container. Es ermittelt automatisch die aktive Container-ID sowie das aktuelle Host-Display und vererbt die X11-Umgebungsvariablen.

• Ausführung:

  ./exec_gui_docker.sh
  

---

🛑 Fehlerbehebung

• Fehler: ❌ Fehler: Kein aktives DISPLAY auf dem Host gefunden!
  • Lösung: Außerhalb von Screen echo $DISPLAY prüfen (z. B. localhost:10.0). In Screen die Variable händisch angleichen: export DISPLAY=localhost:10.0, danach das Skript erneut starten.
• Fehler: X11 connection rejected... beim manuellen Testen
  • Ursache: Das Cookie passt nicht zum Display. Nutze immer run_gui_docker.sh, da dieses das Cookie netzwerkneutral umschreibt.