docs(18-06): Betriebshandbuch Kapitel 10, CI/CD-Runbook Job desktop, Entwicklungshandbuch
- Betriebshandbuch: neues Kapitel 10 (Pipeline-Herkunft, Ablageort im Abbild, Release-Anhaenge, DESKTOP_DIST_DIR, Fehlerbilder-Tabelle); Kapitel 9 um Satz zu Desktop-Paketen im Freigabe-Tag ergaenzt - CI/CD-Runbook: aus drei werden vier Jobs, Job desktop ausfuehrlich beschrieben (Cross-Bau, Cache-Reihenfolge, Cache-vs-upload-artifact- Begruendung), Fehlerbehebung um drei Unterabschnitte ergaenzt (Job desktop, cache miss, Release-Upload 413) - Entwicklungshandbuch: apps/desktop ist kein Grundgeruest mehr, neuer Abschnitt "Desktop-App lokal bauen", Testabschnitt um vitest src/desktop und cargo check/clippy ergaenzt Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -20,6 +20,7 @@ Betrieb der bereits laufenden Installation, nicht deren automatisierten Build.
|
|||||||
7. [Protokolle und Fehlersuche](#7-protokolle-und-fehlersuche)
|
7. [Protokolle und Fehlersuche](#7-protokolle-und-fehlersuche)
|
||||||
8. [Abgrenzung zur CI/CD-Pipeline](#8-abgrenzung-zur-cicd-pipeline)
|
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)
|
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
|
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.
|
`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
|
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
|
„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
|
finden ihn im Repository unter „Releases”. Fehlt der Abschnitt in der
|
||||||
Änderungsliste, schlägt genau dieser letzte Schritt fehl – die Abbilder sind dann
|
Änderungsliste, schlägt genau dieser letzte Schritt fehl – die Abbilder sind dann
|
||||||
trotzdem gebaut und abgelegt. Der Release wird nachgeholt, sobald der Abschnitt
|
trotzdem gebaut und abgelegt. Der Release wird nachgeholt, sobald der Abschnitt
|
||||||
nachgetragen ist: entweder durch erneutes Auslösen des Tag-Laufs oder lokal per
|
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
|
dieses Etikett noch nicht – deshalb erst freigeben, dann installieren. Für einen
|
||||||
Probelauf davor kann vorübergehend `IMAGE_TAG=beta` stehen; danach auf `live`
|
Probelauf davor kann vorübergehend `IMAGE_TAG=beta` stehen; danach auf `live`
|
||||||
umstellen und `pull` + `up -d --force-recreate api web` wiederholen.
|
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. |
|
||||||
|
|||||||
@@ -30,15 +30,23 @@ fest verankert.
|
|||||||
apps/
|
apps/
|
||||||
api/ @tessera/api — NestJS-Backend
|
api/ @tessera/api — NestJS-Backend
|
||||||
web/ @tessera/web — Next.js-Frontend
|
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/
|
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)
|
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
|
`apps/desktop` ist der fertige Desktop-Client (Tauri 2), kein Grundgerüst mehr:
|
||||||
`setup.html` — dort ist noch keine eigentliche Anwendung zu finden. `packages/shared` ist ebenfalls
|
`src-tauri/src/lib.rs` bündelt Tray-Menü, die beiden Erststart-Kommandos
|
||||||
minimal; es enthält aktuell nur eine Konstante und ein Health-Interface, keine DTOs.
|
(`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):
|
**Root-Skripte** (`package.json`, laufen über Turborepo durch alle Workspaces):
|
||||||
|
|
||||||
@@ -117,6 +125,46 @@ postgresql://tessera:tessera_dev@<container-ip>:5432/tessera
|
|||||||
Das ist relevant, sobald Sie `prisma migrate dev`, `prisma studio` oder ein manuelles `psql` **vom
|
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.
|
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
|
## Architektur im Überblick
|
||||||
|
|
||||||
**Frontend** (`apps/web/src/app`, Next.js App Router):
|
**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
|
gegen bereits einmal aufgetretene Fehler — wiederkehrende Fallstricke werden in diesem Projekt
|
||||||
durch einen Test abgesichert, nicht nur durch einen Kommentar.
|
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
|
## Konventionen und Fallstricke
|
||||||
|
|
||||||
**NestJS-Routenreihenfolge:** NestJS matcht Routen in Deklarationsreihenfolge. Eine statische Route
|
**NestJS-Routenreihenfolge:** NestJS matcht Routen in Deklarationsreihenfolge. Eine statische Route
|
||||||
|
|||||||
+115
-9
@@ -109,21 +109,71 @@ hardcoden.
|
|||||||
|
|
||||||
Die CI/CD-Pipeline (`.gitea/workflows/ci.yml`) laeuft bei jedem Push auf die
|
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
|
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,
|
1. **quality** -- Lint und TypeScript Type-Check (Lint ist derzeit ein Leerlauf,
|
||||||
siehe WINDOWS #35; der Type-Check ist echt)
|
siehe WINDOWS #35; der Type-Check ist echt)
|
||||||
2. **test** -- Vitest Unit- und Integrationstests
|
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
|
veroeffentlichen
|
||||||
|
|
||||||
Ablauf: `quality` -> `test` -> `publish` (jeder Job nur bei Erfolg des
|
Ablauf: `quality` -> `test` -> `desktop` -> `publish` (jeder Job nur bei Erfolg
|
||||||
vorherigen). Der Job `publish` besteht aus vier Schritten: `actions/checkout@v4`
|
des vorherigen; `desktop` selbst laeuft nur, wenn die `if`-Bedingung zutrifft
|
||||||
mit `fetch-depth: 0` (volle Historie samt Tags, sonst liefert `git describe`
|
-- auf einem Push nach `live` ohne Tag entfaellt der Job, `publish` startet in
|
||||||
nichts), Login in die Registry (siehe Abschnitt 3), der Aufruf von
|
diesem Fall trotzdem, weil `needs: desktop` bei einem uebersprungenen Job nicht
|
||||||
`.gitea/scripts/publish-images.sh` und der Aufruf von
|
blockiert). Der Job `publish` besteht aus sechs Schritten:
|
||||||
`.gitea/scripts/publish-release.sh` (legt bei Tags `v*` den Gitea-Release aus dem
|
`actions/checkout@v4` mit `fetch-depth: 0` (volle Historie samt Tags, sonst
|
||||||
CHANGELOG-Abschnitt an; auf `main` endet er mit "nichts zu tun").
|
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.
|
Das Release-Skript spricht die Gitea-API ueber `GITHUB_API_URL` bzw.
|
||||||
`GITHUB_SERVER_URL/api/v1` an -- im Job-Container ist das
|
`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`
|
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
|
3. `dev` bedeutet: das Image wurde ohne Build-Args gebaut (lokal statt ueber
|
||||||
das Skript) -- das ist fuer lokale Builds normal
|
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.
|
||||||
|
|||||||
Reference in New Issue
Block a user