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)
|
||||
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. |
|
||||
|
||||
Reference in New Issue
Block a user