LTX-DeskWEB/docs/UPGRADE_INFO.md

Upgrade-Info: Neue LTX-Desktop-Versionen übernehmen

Diese Anleitung beschreibt den vorgesehenen Wartungsablauf für LTX DeskWEB. Sie ist kein automatischer Updater und erteilt keine Freigabe, produktive Dienste oder GPU-Modi umzuschalten. Stand: 29. September 2026.

Ausgangslage und Ziel

LTX DeskWEB verwendet die Oberfläche von LTX Athena / LTX Desktop und ergänzt Browser-Dateizugriff, Anmeldung und HTTP-Weiterleitung. Die Generierung läuft weiterhin im separat verwalteten LTX-Backend auf Athena.

Der erste Import war ein Quellcode-Snapshot, kein Fork mit vollständig übernommener Upstream-Git-Historie. Grundlage und mitübernommene lokale Änderungen stehen in PROVENANCE.md. Daher ist ein einfaches git pull vom Originalprojekt derzeit kein geeigneter Update-Weg. Eine automatisierte Upstream-Synchronisierung ist noch nicht eingerichtet.

GUI und Backend haben getrennte Versionsstände. Neue Funktionen können Änderungen an beiden benötigen. Es wird deshalb immer eine geprüfte Kombination aus Web-GUI, LTX-Backend und gegebenenfalls Modellversion veröffentlicht. Eine neue GUI-Schaltfläche macht eine vom Backend oder Modell nicht unterstützte Funktion nicht verfügbar. Keine automatischen Produktivupdates auf latest.

1. Update prüfen und Vergleichsbasis herstellen

• Release Notes, Änderungen an API/Schema, Projektformat, Abhängigkeiten und Lizenzen im Originalrepository prüfen. Gewünschten Release-Tag und vollständigen Commit festhalten.
• Änderungen nach Oberfläche, Electron/Dateifunktionen und Backend einordnen. Ermitteln, welche neuen Funktionen unsere vorhandene Backend-Version unterstützt.
• Vor dem ersten größeren Update die ursprüngliche Git-Historie in einem separaten Referenz-Checkout bereitstellen. Den in PROVENANCE.md genannten Basis-Commit dort verifizieren und die mitimportierten LTX-Athena-Anpassungen gesondert erfassen. Der lokale Athena-Commit muss nicht im offiziellen Repository existieren; fehlende Herkunft zuerst klären, nicht erraten.
• Den ursprünglichen Snapshot und unsere Browser-Änderungen als nachvollziehbare Vergleichsbasis dokumentieren. Keine erzwungene Zusammenführung unabhängiger Historien und kein Überschreiben der vorhandenen Dateien mit dem neuesten Stand.

2. Isoliert übernehmen

Einen Arbeitsbranch wie codex/ltx-upgrade-<version> anlegen. Vorhandene lokale Änderungen erhalten. Noch keine Änderung an der laufenden Installation.

Die relevanten Upstream-Änderungen gezielt übernehmen und Konflikte prüfen. Besonders wichtig sind:

Bereich	Was erhalten bzw. geprüft werden muss
frontend/lib/web-platform.ts	Browser-Uploads, Medienzugriff und Ersatz der Electron-Funktionen
frontend/App.tsx	Browser-Anmeldung; keine lokale Python-/Modellinstallation
frontend/lib/backend.ts und api-client.ts	Native LTX-API und zur Backend-Version passendes Schema
server/	Zugangsdaten bleiben serverseitig; feste API-Zieladresse; Dateipfadgrenzen
Projektablage / Projektschema	Bestehende Projekte lesbar; Migration und Rückweg geklärt
Docker / Compose	Keine KI-Laufzeit, GPU-Geräte oder Docker-Socket in der GUI

Browser-Anpassungen möglichst in diesen wenigen Grenzen bündeln. Neue Electron-Aufrufe brauchen eine echte Browser-Implementierung oder einen klaren Hinweis, dass die Funktion noch nicht verfügbar ist. Keine simulierten Erfolge. API-Typen nur aus dem passenden Backend-Stand übernehmen beziehungsweise erzeugen; nicht unabhängig auf die neueste Version setzen.

3. Prüfen und Testcontainer bauen

Zunächst die lokalen Prüfungen ausführen:

npm ci
npm run typecheck
npm test
npm run build

Danach ein Image mit eindeutiger Versionskennung bauen. Einen separaten Testcontainer mit anderem Namen, freiem Port, eigener Browser-Origin und eigenen Testdateien starten. Die laufende GUI bleibt erhalten. Keine bestehenden Produktivdaten für Migrationstests verändern; gesicherte Kopien verwenden.

Achtung: Das Athena-Override enthält einen festen Container-Namen sowie Host- Networking. Nur einen anderen Compose-Projektnamen zu wählen reicht deshalb nicht. Auch container_name, der tatsächlich verwendete Server-PORT und PUBLIC_ORIGIN müssen im Test-Override angepasst werden. Bei Host-Networking bewirkt eine andere Portveröffentlichung allein nichts.

Testreihenfolge:

1. Synthetisches Backend und Testmedien für Anmeldung, Upload, Vorschau, Downloads, Dateisicherheit und Fehlermeldungen verwenden.
2. Projekte anlegen, bearbeiten, sichern, wiederherstellen und nach Neuladen öffnen. Alte Projektkopien prüfen, bevor eine Migration freigegeben wird.
3. Native API-Verträge einschließlich Fehlerantworten und Modellfähigkeiten vergleichen. Nicht verfügbare Funktionen korrekt ausblenden oder erklären.
4. Nach Freigabe eines geeigneten GPU-Testfensters mit dem echten LTX-Backend Generierung, Fortschritt, Abbruch, Ergebnisübernahme und Wiederverbindung testen. Die alte GUI darf dabei weiter laufen; beide GUIs teilen aber dasselbe Backend und damit dessen Jobs/GPU-Zustand. Ein zweiter GUI-Container isoliert keine Generierung. Keine parallelen konkurrierenden Testaufträge starten.
5. Die neu übernommenen Funktionen gezielt testen, z. B. Bild-/Audioeingabe, Extend, Retake oder LoRA — jeweils nur, soweit das konkrete Modell sie unterstützt.

Ein erfolgreicher Frontend-Build oder synthetischer Test ersetzt keinen echten Backend-Integrationstest. Nicht geprüfte Funktionen ausdrücklich dokumentieren.

4. Release vorbereiten und ausrollen

Vor der Umstellung festhalten:

• Web-GUI-Commit, Version und Image-Digest.
• Übernommener Upstream-Release/Commit sowie LTX-Backend-Version und Image-Digest.
• Geprüfte Modellversionen, neue Funktionen, Einschränkungen und Testergebnisse.
• Änderungen an Konfiguration, API und Projektformat.
• Vorheriger funktionierender Stand und konkreter Rückfallweg.

Projekte vor einer Formatänderung sichern. Die erste Web-Version speichert sie im Browser: Das Sichern nur des Containers genügt nicht. JSON-Backup und zugehörige Medien getrennt erhalten; das JSON enthält keine Mediendateien. Konfiguration und Secrets geschützt außerhalb von Git sichern, ohne sie auszugeben.

Erst nach erfolgreichen Prüfungen den GUI-Container gezielt ersetzen. Eine nötige Backend-Aktualisierung gesondert planen; laufende Generierungen vorher beenden lassen oder einen Abbruch ausdrücklich abstimmen. Andere Athena-Dienste bleiben unverändert. GUI-Update und Backend-Update sind keine pauschale Freigabe für Treiber-, Netzwerk-, WireGuard- oder Hoständerungen.

Nach dem Rollout Erreichbarkeit, Anmeldung, Deck-Dienstliste und native API-Verbindung prüfen. Den alten Image-Stand bis zum Abschluss der Abnahme behalten. Betriebsbefehle: ATHENA_DEPLOYMENT.md.

5. Rückfall

Bei Problemen die vorherige GUI-Version mit ihrer bekannten Konfiguration starten. Wurde auch das Backend verändert, die zuvor geprüfte Kombination wiederherstellen. Keine Modellgewichte oder Nutzerdaten beim Rückwechsel löschen.

Ein Image-Rollback macht eine Datenmigration nicht rückgängig. Hat die neue Version Projekte inkompatibel verändert, vorher sichern und die passenden Projektkopien wiederherstellen. Deshalb Migrationen zuerst an Kopien prüfen und Backups nicht mit migrierten Daten überschreiben.

Noch vorzubereiten

• Verifizierte Upstream-Vergleichsbasis einschließlich der lokalen Athena-Patches.
• Wiederholbarer Testcontainer-Workflow mit isolierten Daten und Ports.
• Dokumentierte Kompatibilitätsmatrix GUI ↔ Backend ↔ Modell.
• Erweiterte Integrationstests für lang laufende Jobs und Projektmigrationen.

Diese Punkte sind geplant; diese Datei behauptet nicht, dass sie bereits implementiert sind. Nach jedem Upgrade PROVENANCE.md, VALIDATION.md und die Kompatibilitätsangaben aktualisieren.