meldestelle/docs/02_Guides/Desktop-Packaging-Guide.md

📦 Guide: Desktop App Packaging (Conveyor & Gradle)

Dieses Dokument beschreibt den professionellen Packaging-Prozess für die Meldestelle Desktop App. Wir nutzen Conveyor als primäres Werkzeug für das Cross-Platform Packaging (Windows, Linux, macOS), da es stabile Installer inklusive signierter Updates und gebündelter JREs erzeugt.

---

1. Strategie: Conveyor vs. Gradle

Feature	Conveyor (Empfohlen)	Gradle (Compose Plugin)
Zielgruppe	Endanwender (Produktion)	Entwickler (Lokaler Test)
Plattformen	Windows (.msix), Linux (.deb), macOS	Nur Host-OS (Linux auf Linux)
Updates	Automatisch integriert	Manuell
JRE	Amazon Corretto (isoliert)	System JRE oder Toolchain

---

2. Cross-Packaging mit Conveyor

Conveyor ist so konfiguriert, dass es von Linux aus Pakete für alle Zielsysteme schnüren kann.

Voraussetzungen

1. JAR-Dateien: Die App muss kompiliert sein:

   ./gradlew :frontend:shells:meldestelle-desktop:jvmJar
   

2. Icons: Das System sucht nach icon.png in frontend/shells/meldestelle-desktop/src/jvmMain/resources/.

Pakete bauen

Führen Sie Conveyor im Projekt-Root aus:

# Komplette Release-Site (Windows & Linux)
conveyor make site

# Nur ein spezifisches Paket (schneller für Tests)
conveyor make debian-package   # Linux .deb
conveyor make windows-msix      # Windows .msix

Die Ergebnisse liegen im Ordner output/.

---

3. Konfiguration (conveyor.conf)

Wichtige Parameter der aktuellen Konfiguration (v1.0.1):

• JDK: Nutzt Amazon Corretto 21 für maximale Cross-Platform Stabilität.
• Heap-Size: Erhöht auf -Xmx1024m, um auch große Stammdaten-Importe zu bewältigen.
• Linux-Deps: Automatische Installation von libasound2, libgl1-mesa-glx und libx11-6.
• Native Access: --enable-native-access=ALL-UNNAMED ist für Netty/SQLite aktiviert.

---

4. Netzwerk & Sicherheit (WICHTIG)

Damit die P2P-Funktionen (Chat, Discovery, Sync) nach der Installation funktionieren, müssen folgende Ports auf dem Host-System offen sein:

Port	Protokoll	Funktion
8080	TCP	P2P Sync & Datenabgleich
8090	TCP	Veranstaltungs-Chat (WebSocket)
5353	UDP	mDNS Discovery (Geräte finden)

Firewall-Einrichtung (Linux)

Nutzen Sie das optimierte Setup-Script:

sudo ./setup-firewall-linux.sh

Windows-Besonderheit

Beim ersten Start der .msix App wird Windows fragen, ob der Netzwerkzugriff erlaubt werden soll. Wichtig: Sowohl "Private" als auch "Öffentliche" Netzwerke anhaken, falls auf Turnieren oft Gast-WLANs oder Hotspots genutzt werden.

---

5. Troubleshooting

Problem: "No main class specified"

Lösung: Stellen Sie sicher, dass in der Main.kt eine saubere Top-Level fun main() existiert und in der conveyor.conf auf at.mocode.frontend.shell.desktop.MainKt verwiesen wird.

Problem: SQLite / Native Libs laden nicht

Lösung: Prüfen Sie, ob extract-native-libraries.conf in der conveyor.conf inkludiert ist.

Problem: JmDNS findet keine Teilnehmer

Lösung: Prüfen Sie die Ports via ss -tulpn. Auf Linux blockieren oft Docker-Interfaces (br-*) den Broadcast. Die App filtert diese nun automatisch, aber ein aktives setup-firewall-linux.sh ist zwingend erforderlich.

6. Performance-Optimierung (Gradle)

Der Build-Prozess kann bei aktivierter Web-Kompilierung (WASM/JS) sehr lange dauern. Für die reine Desktop-Entwicklung wurde WASM standardmäßig deaktiviert.

• WASM aktivieren (z.B. für CI/Portal): ./gradlew -PenableWasm=true ...
• WASM deaktivieren (Default): ./gradlew ... (Spart bis zu 70% Build-Zeit).

Stellen Sie in der gradle.properties sicher, dass enableWasm=false gesetzt ist, wenn Sie primär an der Desktop-App arbeiten.