From 64573e01a3159d28c7ed406667035e926245b588 Mon Sep 17 00:00:00 2001 From: Mikei386 <44135113+Mikei386@users.noreply.github.com> Date: Tue, 29 Sep 2026 19:40:34 +0200 Subject: [PATCH] Document upstream upgrade and rollback workflow --- README.md | 2 + docs/UPGRADE_INFO.md | 150 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 152 insertions(+) create mode 100644 docs/UPGRADE_INFO.md diff --git a/README.md b/README.md index c40539e..430a351 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,8 @@ Athena installation and operation: [deployment guide](docs/ATHENA_DEPLOYMENT.md) See [limitations and architecture](docs/ARCHITECTURE.md) and [provenance](docs/PROVENANCE.md). +Future upstream updates: [Upgrade-Info (Deutsch)](docs/UPGRADE_INFO.md). + ## Debian / Docker deployment Prerequisites: Docker Engine + Compose; a separately configured LTX Desktop backend; diff --git a/docs/UPGRADE_INFO.md b/docs/UPGRADE_INFO.md new file mode 100644 index 0000000..3962a8d --- /dev/null +++ b/docs/UPGRADE_INFO.md @@ -0,0 +1,150 @@ +# 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](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](https://github.com/Lightricks/LTX-Desktop) + 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-` 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: + +```sh +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](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.