diff --git a/docs/anleitung-betrieb.md b/docs/anleitung-betrieb.md index 21b6e2f..2b7e41b 100644 --- a/docs/anleitung-betrieb.md +++ b/docs/anleitung-betrieb.md @@ -20,6 +20,7 @@ Betrieb der bereits laufenden Installation, nicht deren automatisierten Build. 7. [Protokolle und Fehlersuche](#7-protokolle-und-fehlersuche) 8. [Abgrenzung zur CI/CD-Pipeline](#8-abgrenzung-zur-cicd-pipeline) 9. [Zwei Kanäle: Live und Beta](#9-zwei-kanäle-live-und-beta) +10. [Desktop-App: Pakete und Release-Dateien](#10-desktop-app-pakete-und-release-dateien) --- @@ -450,9 +451,13 @@ weigert, ist eine frühere Korrektur (siehe Hotfix, Schritt 5) noch nicht zurüc Zweig `live` wird nur geprüft, der Tag `vX.Y.Z` wird gebaut und als `live` und `vX.Y.Z` abgelegt. Das dauert etwa vier bis sechs Minuten. +Derselbe Tag baut zusätzlich die Desktop-Pakete (Windows-Installer und +Linux-AppImage) und hängt beide als Dateien an denselben Release an – Details +dazu in [Kapitel 10](#10-desktop-app-pakete-und-release-dateien). + Beim Tag legt die Pipeline zusätzlich einen **Release in Gitea** an: Name -„Tessera X.Y.Z“, Text ist der Abschnitt dieser Version aus `CHANGELOG.md`. Sie -finden ihn im Repository unter „Releases“. Fehlt der Abschnitt in der +„Tessera X.Y.Z”, Text ist der Abschnitt dieser Version aus `CHANGELOG.md`. Sie +finden ihn im Repository unter „Releases”. Fehlt der Abschnitt in der Änderungsliste, schlägt genau dieser letzte Schritt fehl – die Abbilder sind dann trotzdem gebaut und abgelegt. Der Release wird nachgeholt, sobald der Abschnitt nachgetragen ist: entweder durch erneutes Auslösen des Tag-Laufs oder lokal per @@ -543,3 +548,70 @@ Kapitel 2 gilt vollständig. Die Abweichungen gegenüber alpha: dieses Etikett noch nicht – deshalb erst freigeben, dann installieren. Für einen Probelauf davor kann vorübergehend `IMAGE_TAG=beta` stehen; danach auf `live` umstellen und `pull` + `up -d --force-recreate api web` wiederholen. + +## 10. Desktop-App: Pakete und Release-Dateien + +Seit September 2026 gibt es Tessera zusätzlich als Desktop-App für Windows und +Linux. Dieses Kapitel beschreibt, woher die Pakete kommen, wo sie liegen und +wie Sie Fehlerbilder rund um den Download einordnen. Die Anwendersicht (Download, +Installation, SmartScreen-Hinweis, Bedienung) steht in +`docs/anleitung-anwender.md`, Kapitel „Desktop-App". + +### Woher die Pakete kommen + +Der CI-Job `desktop` läuft nach `test` und vor `publish` – auf Push nach `main` +und bei jedem Freigabe-Tag `v*`. In diesem einen Job entstehen auf dem +Linux-Runner sowohl das Linux-AppImage als auch der Windows-Installer per +Cross-Bau (`cargo-xwin` + NSIS aus dem Ubuntu-Paket, kein Windows-Rechner in +der Pipeline). Einzelheiten zur Werkzeugkette stehen in +[`docs/ci-cd-setup.md`](./ci-cd-setup.md), Abschnitt 4. + +### Wo die Pakete im Abbild liegen + +`publish` kopiert die fertigen Pakete in das API-Abbild nach +`/app/desktop-dist/`, zusammen mit einer `manifest.json` (Version, Kanal, +Dateinamen, Größen, Prüfsummen). Auf dem Beta-Kanal tragen die Dateinamen +zusätzlich den Suffix `-beta.{commit}`, zum Beispiel +`Tessera-Setup-1.1.0-beta.742fb5c.exe` und +`Tessera-1.1.0-beta.742fb5c.AppImage`; auf Live steht dort die reine Form +`Tessera-Setup-X.Y.Z.exe` / `Tessera-X.Y.Z.AppImage`. + +Kontrolle auf dem Server: + +```bash +docker compose exec api ls -l /app/desktop-dist +curl -s https://{ihre-adresse}/api-proxy/desktop/latest +``` + +`ls -l` zeigt die abgelegten Dateien samt `manifest.json`; die `curl`-Abfrage +liefert dieselben Angaben als JSON (Version, Kanal, je Plattform Dateiname, +Größe, Prüfsumme und relative Download-Adresse) – das ist genau die Antwort, +die auch die Anmeldeseite und die Einstellungsseite auswerten. Antwortet die +Abfrage mit `404`, fehlt entweder das Verzeichnis oder das Manifest; die +Web-Oberfläche blendet den Download-Link dann automatisch aus. + +### Release-Dateien in Gitea + +Bei einem Freigabe-Tag hängt die Pipeline zusätzlich beide Dateien aus dem +Manifest als Anhänge an den Gitea-Release desselben Tags (Kapitel 9, „Eine +Version freigeben") – idempotent: ein erneuter Lauf ersetzt eine bereits +vorhandene Datei gleichen Namens, statt einen zweiten Anhang anzulegen. Die am +Release hinterlegte Datei ist byteidentisch mit der im Abbild ausgelieferten; +die Prüfsumme (`sha256`) aus `manifest.json` gilt für beide gleichermaßen. + +### Umgebungsvariablen + +Für die Desktop-Auslieferung ist keine neue Pflichtvariable nötig. + +| Variable | Pflicht? | Default | Zweck | +|----------|:---:|---|---| +| `DESKTOP_DIST_DIR` | nein | `/app/desktop-dist` (im Abbild) | Ablageort der Desktop-Pakete und der `manifest.json`, aus dem `GET /desktop/latest` und `GET /desktop/download/:platform` lesen. In der Regel nicht ändern. | + +### Fehlerbilder + +| Symptom | Wahrscheinliche Ursache | Prüfen / Beheben | +|---|---|---| +| Download-Link fehlt auf der Anmeldeseite bzw. `/api-proxy/desktop/latest` liefert `404` | Das laufende Abbild trägt keine Desktop-Pakete – der Job `publish` hätte ohne Manifest eigentlich abbrechen müssen | Den zugehörigen Pipeline-Lauf prüfen (Job `desktop`/`publish` grün?), danach `docker compose pull` + `up -d --force-recreate api` erneut ausführen. | +| Download bricht bei großen Dateien ab | Größengrenze oder Zeitlimit des vorgeschalteten Proxys (Nginx Proxy Manager) – `client_max_body_size` bzw. Timeout-Einstellungen | Proxy-Konfiguration für die betroffene Adresse prüfen und die Grenze anheben. | +| Client meldet „Unter dieser Adresse antwortet kein Tessera-Server" | Anwender hat die interne API-Adresse statt der Web-Adresse eingetragen, oder `/api-proxy` ist vom Client-Rechner aus nicht erreichbar | Die im Anwenderhandbuch beschriebene Adresse verwenden (dieselbe wie im Browser); Netzwerk-/Firewall-Erreichbarkeit der Web-Adresse prüfen. | +| Windows zeigt die SmartScreen-Warnung | Erwartet – die App ist für den internen Gebrauch nicht signiert (D-09) | Kein Fehler; Anwenderhandbuch, Abschnitt „Installation unter Windows", beschreibt den Ablauf. | diff --git a/docs/anleitung-entwicklung.md b/docs/anleitung-entwicklung.md index a722b02..a593d18 100644 --- a/docs/anleitung-entwicklung.md +++ b/docs/anleitung-entwicklung.md @@ -30,15 +30,23 @@ fest verankert. apps/ api/ @tessera/api — NestJS-Backend web/ @tessera/web — Next.js-Frontend - desktop/ — — Tauri-Wrapper, früher Stand (nur Cargo-Projekt + eine setup.html) + desktop/ @tessera/desktop — Tauri-Desktop-Client (Windows/Linux), fertiges Produkt packages/ - shared/ @tessera/shared — geteilte Konstanten/Typen, derzeit sehr klein (APP_NAME, HealthResponse) + shared/ @tessera/shared — geteilte Konstanten/Typen, inzwischen auch die Manifest-Typen der Desktop-Pakete module-sdk/ — — TypeScript-Interfaces für den Modul-Vertrag (TesseraModule, ModuleManifest) ``` -`apps/desktop` besteht bislang nur aus dem Tauri-Grundgerüst (`src-tauri/`) und einer einzelnen -`setup.html` — dort ist noch keine eigentliche Anwendung zu finden. `packages/shared` ist ebenfalls -minimal; es enthält aktuell nur eine Konstante und ein Health-Interface, keine DTOs. +`apps/desktop` ist der fertige Desktop-Client (Tauri 2), kein Grundgerüst mehr: +`src-tauri/src/lib.rs` bündelt Tray-Menü, die beiden Erststart-Kommandos +(`check_server`/`save_server_url`) und die Versionsprüfung gegen den Server; +`src/setup.html` ist die eigenständige Erststart-Seite (kein Bundler, spricht +nur über `window.__TAURI__.core.invoke`). Die fertigen Installationspakete +(Windows-`.exe`, Linux-`.AppImage`) entstehen nicht lokal, sondern im CI-Job +`desktop` (siehe [Desktop-App lokal bauen](#desktop-app-lokal-bauen) für den +lokalen Linux-Bau). `packages/shared` bleibt schlank, trägt inzwischen aber +zusätzlich zu Konstante und Health-Interface auch die Typen für das +Desktop-Paket-Manifest (`DesktopPlatform`, `DesktopManifest`, +`DesktopLatestResponse`). **Root-Skripte** (`package.json`, laufen über Turborepo durch alle Workspaces): @@ -117,6 +125,46 @@ postgresql://tessera:tessera_dev@:5432/tessera Das ist relevant, sobald Sie `prisma migrate dev`, `prisma studio` oder ein manuelles `psql` **vom Host aus** statt aus dem `api`-Container heraus ausführen wollen. +### Desktop-App lokal bauen + +Voraussetzungen zusätzlich zu oben: + +- Rust (stable) über [rustup](https://rustup.rs/) +- Auf Ubuntu/Debian folgende Systempakete: + ```bash + sudo apt-get install -y libwebkit2gtk-4.1-dev libjavascriptcoregtk-4.1-dev \ + libayatana-appindicator3-dev librsvg2-dev libgtk-3-dev libssl-dev patchelf + ``` + +Version setzen und Linux-Paket bauen: + +```bash +sh .gitea/scripts/desktop-version.sh +pnpm --filter @tessera/desktop exec tauri build --bundles appimage +``` + +`desktop-version.sh` schreibt die Version des letzten Freigabe-Tags in +`tauri.conf.json`/`Cargo.toml` — die im Repository eingecheckten Versionsdateien +sind nur eine Basislinie, nicht die tatsächliche Freigabeversion. Das fertige +Paket liegt danach unter +`apps/desktop/src-tauri/target/release/bundle/appimage/`. Um es wie die +API es ausliefern würde einzusammeln: + +```bash +sh .gitea/scripts/desktop-collect.sh --require linux +``` + +Das schreibt `desktop-dist/` (per `.gitignore` vom Git ausgeschlossen, bis auf +einen Platzhalter) samt `manifest.json`. Starten Sie danach den lokalen +Docker-Stack (`docker compose build api` genügt für die API allein), liefert +`GET /desktop/latest` die dort abgelegten Pakete aus. + +**Der Windows-Installer wird nur im CI gebaut** (`cargo-xwin`-Cross-Bau, NSIS +aus dem Ubuntu-Paket `nsis` — siehe `docs/ci-cd-setup.md`, Abschnitt 4). Lokal +genügt für Rust-Änderungen `cargo check`/`cargo clippy` in +`apps/desktop/src-tauri`; einen Windows-Installer lokal zu bauen ist nicht +vorgesehen. + ## Architektur im Überblick **Frontend** (`apps/web/src/app`, Next.js App Router): @@ -422,6 +470,27 @@ gegen Services, Controller-Logik und React-Komponenten. Guard-artige Spezifikati gegen bereits einmal aufgetretene Fehler — wiederkehrende Fallstricke werden in diesem Projekt durch einen Test abgesichert, nicht nur durch einen Kommentar. +**Desktop-Modul (`apps/api/src/desktop`):** + +```bash +pnpm --filter @tessera/api exec vitest run src/desktop +``` + +Die Tests laufen als echter HTTP-Durchstich über `NestFactory.create()` + +`app.listen(0)` gegen ein echtes temporäres Verzeichnis (kein `fs`-Mock) — +Manifest lesen, 404 ohne Manifest, Plattform-Whitelist, Pfad-Traversal +abgewiesen. + +**Rust (`apps/desktop/src-tauri`):** + +```bash +cargo check +cargo clippy +``` + +Beide laufen auch im CI-Job `desktop` (D-16); ein grüner `cargo clippy` ohne +Warnungen ist Voraussetzung für den Bauschritt. + ## Konventionen und Fallstricke **NestJS-Routenreihenfolge:** NestJS matcht Routen in Deklarationsreihenfolge. Eine statische Route diff --git a/docs/ci-cd-setup.md b/docs/ci-cd-setup.md index 207ca3c..a44c2c6 100644 --- a/docs/ci-cd-setup.md +++ b/docs/ci-cd-setup.md @@ -109,21 +109,71 @@ hardcoden. Die CI/CD-Pipeline (`.gitea/workflows/ci.yml`) laeuft bei jedem Push auf die Zweige `main` und `live` sowie bei jedem Tag `v*` (z. B. `v1.0.0`) und besteht -aus drei aufeinander aufbauenden Jobs: +aus vier aufeinander aufbauenden Jobs: 1. **quality** -- Lint und TypeScript Type-Check (Lint ist derzeit ein Leerlauf, siehe WINDOWS #35; der Type-Check ist echt) 2. **test** -- Vitest Unit- und Integrationstests -3. **publish** -- Docker Images mit Versionsstempel bauen und in die Gitea-Registry +3. **desktop** -- Desktop-Pakete fuer Windows und Linux bauen (nur auf `main` + und bei Tags `v*`, siehe unten) +4. **publish** -- Docker Images mit Versionsstempel bauen und in die Gitea-Registry veroeffentlichen -Ablauf: `quality` -> `test` -> `publish` (jeder Job nur bei Erfolg des -vorherigen). Der Job `publish` besteht aus vier Schritten: `actions/checkout@v4` -mit `fetch-depth: 0` (volle Historie samt Tags, sonst liefert `git describe` -nichts), Login in die Registry (siehe Abschnitt 3), der Aufruf von -`.gitea/scripts/publish-images.sh` und der Aufruf von -`.gitea/scripts/publish-release.sh` (legt bei Tags `v*` den Gitea-Release aus dem -CHANGELOG-Abschnitt an; auf `main` endet er mit "nichts zu tun"). +Ablauf: `quality` -> `test` -> `desktop` -> `publish` (jeder Job nur bei Erfolg +des vorherigen; `desktop` selbst laeuft nur, wenn die `if`-Bedingung zutrifft +-- auf einem Push nach `live` ohne Tag entfaellt der Job, `publish` startet in +diesem Fall trotzdem, weil `needs: desktop` bei einem uebersprungenen Job nicht +blockiert). Der Job `publish` besteht aus sechs Schritten: +`actions/checkout@v4` mit `fetch-depth: 0` (volle Historie samt Tags, sonst +liefert `git describe` nichts), der Wiederherstellung der Desktop-Pakete aus +dem Zwischenspeicher, einer harten Pruefung des Manifests, Login in die +Registry (siehe Abschnitt 3), der Aufruf von `.gitea/scripts/publish-images.sh` +und der Aufruf von `.gitea/scripts/publish-release.sh` (legt bei Tags `v*` den +Gitea-Release aus dem CHANGELOG-Abschnitt an und haengt die Desktop-Pakete als +Dateien an; auf `main` endet er mit "nichts zu tun"). + +### Job `desktop`: Windows- und Linux-Pakete auf dem Linux-Runner + +Der Job `desktop` baut auf demselben `ubuntu-latest`-Runner nacheinander (ein +Cache, ein Runner, siehe `18-CONTEXT.md` Specific Ideas) sowohl das +Linux-AppImage als auch -- per Cross-Bau -- den Windows-Installer: + +1. **Systemabhaengigkeiten** (`apt-get install`): WebKit/Tauri-Pakete + (`libwebkit2gtk-4.1-dev` usw.) fuer den Linux-Bau, dazu `lld llvm clang + nsis` fuer den Windows-Cross-Bau (der NSIS-Bundler ruft `makensis` aus + genau diesem Paket auf). +2. **Rust-Toolchain** per `rustup` (kein Rust im Runner-Abbild), inklusive + `rustup component add clippy` -- `--profile minimal` installiert `clippy` + sonst nicht mit (siehe Fehlerbehebung unten). +3. **Cargo-Zwischenspeicher** (`actions/cache@v4`, Schluessel ueber den Hash + von `Cargo.lock`): `~/.cargo/registry`, `~/.cargo/git`, + `~/.cargo/bin/cargo-xwin`, `~/.cache/cargo-xwin` (die von `cargo-xwin` + heruntergeladene Windows-SDK-Ablage -- soll nur einmal geladen werden), + `~/.local/share/tauri` (NSIS-Plugins) und `apps/desktop/src-tauri/target`. +4. **Windows-Werkzeuge** -- bewusst NACH dem Cache-Wiederherstellungsschritt: + `rustup target add x86_64-pc-windows-msvc` und + `command -v cargo-xwin || cargo install --locked cargo-xwin`. Stuende + dieser Schritt vor der Cache-Wiederherstellung, wuerde `cargo-xwin` bei + jedem Lauf neu gebaut, selbst wenn der Cache es bereits enthaelt. +5. **Version setzen** (`desktop-version.sh`), **Rust pruefen** + (`cargo check`/`cargo clippy`, D-16), Bau des Linux-AppImage + (`tauri build --bundles appimage`), dann des Windows-Installers per + Cross-Bau (`tauri build --runner cargo-xwin --target + x86_64-pc-windows-msvc --bundles nsis`). +6. **Pakete einsammeln** (`desktop-collect.sh --require linux,windows`) -- + schreibt `manifest.json` und schlaegt fehl, wenn eine der beiden Dateien + fehlt. +7. **Uebergabe an `publish`** per `actions/cache/save@v4` mit dem Schluessel + `desktop-dist-${{ gitea.sha }}` (ein neuer Schluessel je Commit, damit + `publish` garantiert die Pakete des gerade gebauten Standes bekommt, nicht + einen aelteren Cache-Treffer). + +**Warum `actions/cache` und nicht `upload-artifact`:** Auf dieser +Gitea-Instanz ist `actions/upload-artifact`/`download-artifact` unzuverlaessig +(Erfahrungswert aus 18-02) -- die Uebergabe zwischen `desktop` und `publish` +laeuft deshalb bewusst ueber `actions/cache/save` und +`actions/cache/restore` mit `fail-on-cache-miss: true`, nicht ueber +Artefakt-Uploads. Das Release-Skript spricht die Gitea-API ueber `GITHUB_API_URL` bzw. `GITHUB_SERVER_URL/api/v1` an -- im Job-Container ist das @@ -237,3 +287,59 @@ und einen Branch-Schutz fuer `live` anlegen (T-KU1-04). 2. Pruefen, ob der Tag wirklich gepusht wurde: `git ls-remote --tags origin` 3. `dev` bedeutet: das Image wurde ohne Build-Args gebaut (lokal statt ueber das Skript) -- das ist fuer lokale Builds normal + +### Job `desktop` schlaegt fehl + +1. **`cargo clippy` meldet `'cargo-clippy' is not installed for the toolchain`** + -- der Schritt "Rust-Toolchain" installiert mit `--profile minimal`, das + `clippy` nicht mitbringt. Behoben durch `rustup component add clippy` + direkt nach der Toolchain-Installation (siehe oben); bei einem aehnlichen + Fehlerbild in Zukunft pruefen, ob diese Zeile noch vorhanden ist. +2. **apt-Paketname unbekannt / `pkg-config` findet eine Bibliothek nicht** -- + Paketnamen aendern sich gelegentlich zwischen Ubuntu-Versionen des + Runner-Abbilds; den fehlenden `.pc`/`.so`-Namen aus der Fehlermeldung in + `apt-cache search` nachschlagen und die Paketliste im Schritt + "Systemabhaengigkeiten" ergaenzen. +3. **`openssl-sys` scheitert beim Windows-Cross-Ziel** -- OpenSSL laesst sich + fuer `x86_64-pc-windows-msvc` von Linux aus nicht ohne Weiteres + cross-kompilieren; falls eine neue Abhaengigkeit das ueber `openssl-sys` + statt `rustls-tls` einzieht, das Feature/die Abhaengigkeit auf + `rustls-tls` umstellen (in diesem Job bislang nicht aufgetreten, `reqwest` + ist bereits auf `rustls-tls` konfiguriert). +4. **NSIS-Plugin-Download schlaegt fehl** -- Tauris NSIS-Bundler laedt beim + ersten Bau zusaetzliche Plugins nach `~/.local/share/tauri`; ein + Netzwerkfehler dort bricht den Bauschritt "Windows-Installer bauen + (Cross-Bau)" ab. Lauf erneut anstossen; bleibt der Cache warm, entfaellt + der Download beim naechsten Mal. +5. **Runner-Speicher/-Zeit reicht nicht** -- der Rust-Bau laeuft auf einem + begrenzten Runner (8 Kerne/15 GB, siehe `18-CONTEXT.md`); bei + Speicherdruck `CARGO_BUILD_JOBS` (z. B. auf `4`) als Umgebungsvariable im + Job setzen, um die parallele Uebersetzung zu drosseln. + +### `publish`: cache miss + +`actions/cache/restore@v4` mit `fail-on-cache-miss: true` bricht den Job +`publish` hart ab, wenn kein Eintrag unter dem Schluessel +`desktop-dist-${{ gitea.sha }}` existiert. Wahrscheinlichste Ursachen: + +1. Der Job `desktop` ist fehlgeschlagen oder uebersprungen worden (siehe + `if`-Bedingung oben) -- im Gitea-Actions-Lauf pruefen, ob `desktop` + tatsaechlich gruen war. +2. Der Zwischenspeicher-Server des `act_runner` ist nicht erreichbar oder + nicht aktiviert -- Runner-Konfiguration pruefen (Abschnitt 2, + `[cache] enabled` muss gesetzt sein). +3. Der Commit-SHA im Schluessel weicht zwischen den Jobs ab (sollte bei + `gitea.sha` innerhalb desselben Laufs nicht vorkommen) -- bei Verdacht die + Job-Logs beider Schritte (`Uebergabe an publish` in `desktop`, + `Desktop-Pakete aus dem Zwischenspeicher holen` in `publish`) auf den + verwendeten Schluessel vergleichen. + +### Release-Upload 413 + +Schlaegt der Datei-Upload in `publish-release.sh` mit HTTP 413 (Datei zu +gross) fehl, blockt vermutlich der vorgeschaltete Proxy vor `git.vicolab.de` +den grossen Installer-Upload -- dasselbe bekannte Verhalten wie beim +Image-Push (Abschnitt 3). Abhilfe: `GITEA_API` auf die Host-Adresse +`http://172.18.0.1:3002/api/v1` setzen, damit der Release-Upload denselben +Weg wie der Registry-Push nimmt und den Proxy umgeht -- nur noetig, wenn der +Proxy die Groesse tatsaechlich abweist.