docs(quick-260914-ku1): Betriebshandbuch — Zwei Kanäle Live und Beta, Freigabe, Hotfix ohne Datenbankänderung, neuer Live-Server; ci-cd-setup auf gemessenen Stand
- anleitung-betrieb.md: neues Kapitel 9 (Kanal, IMAGE_TAG je Server, Freigabe, Hotfix-Ablauf mit Regel "Keine Datenbankaenderung als Hotfix", drei Kontrollwege, Einrichtung des Live-Servers, Erstfreigabe v1.0.0); Inhaltsverzeichnis, Tabelle in Kapitel 1, IMAGE_TAG in Kapitel 3, Etiketten in Kapitel 4, Startzeile in Kapitel 7 - ci-cd-setup.md: REGISTRY_TOKEN und Push ueber localhost:3002, Trigger main/live/v*, Jobs quality -> test -> publish, Etiketten- und Build-Arg-Tabellen, D-13 ueberholt, Tag-/Branch-Schutz-Empfehlung (T-KU1-04), Fehlerbehebung fuer den Stempel Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018N9CD3ebPKm1b32bPpBknY
This commit is contained in:
+81
-19
@@ -80,11 +80,24 @@ docker ps --filter name=gitea-runner
|
||||
|
||||
### Gitea Secrets (fuer die CI-Pipeline)
|
||||
|
||||
In Gitea unter **Repository > Settings > Actions > Secrets** koennen Secrets
|
||||
fuer die Pipeline konfiguriert werden. Aktuell werden keine Secrets in der
|
||||
Pipeline benoetigt, da Images lokal gebaut und deployed werden (kein Registry-Push).
|
||||
In Gitea unter **Repository > Settings > Actions > Secrets** werden die Secrets
|
||||
fuer die Pipeline konfiguriert. Benoetigt wird genau eines:
|
||||
|
||||
Falls kuenftig Deploy-Pfade oder Credentials benoetigt werden:
|
||||
| Secret | Beschreibung |
|
||||
|--------|--------------|
|
||||
| `REGISTRY_TOKEN` | Gitea-Zugangstoken (Access Token) mit Schreibrecht auf Pakete (`package: write`). Wird im Job `publish` fuer `docker login localhost:3002 --password-stdin` verwendet. |
|
||||
|
||||
Das Token erscheint nie im Log: es wird per `--password-stdin` uebergeben und
|
||||
Gitea maskiert Secret-Werte in der Job-Ausgabe. Das Veroeffentlichungs-Skript
|
||||
`.gitea/scripts/publish-images.sh` kennt das Token nicht; der Login bleibt im
|
||||
Workflow.
|
||||
|
||||
Der Push geht ueber `localhost:3002` (Gitea laeuft auf demselben Rechner wie der
|
||||
Runner), weil der Nginx Proxy Manager vor `git.vicolab.de` grosse Image-Blobs
|
||||
blockt. Das Pullen auf den Servern laeuft ueber `git.vicolab.de`
|
||||
(`docker-compose.prod.yml`).
|
||||
|
||||
Weitere Secrets bei Bedarf:
|
||||
|
||||
1. In Gitea **Settings > Actions > Secrets** den Secret anlegen
|
||||
2. In `.gitea/workflows/ci.yml` ueber `${{ secrets.SECRET_NAME }}` referenzieren
|
||||
@@ -94,27 +107,62 @@ hardcoden.
|
||||
|
||||
## 4. Pipeline-Ueberblick
|
||||
|
||||
Die CI/CD-Pipeline (`.gitea/workflows/ci.yml`) wird bei jedem Push auf `main`
|
||||
ausgefuehrt und besteht aus drei aufeinander aufbauenden Jobs:
|
||||
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:
|
||||
|
||||
1. **quality** -- Lint (Biome) und TypeScript Type-Check
|
||||
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. **build-deploy** -- Docker Images bauen und Services neu starten
|
||||
3. **publish** -- Docker Images mit Versionsstempel bauen und in die Gitea-Registry
|
||||
veroeffentlichen
|
||||
|
||||
Ablauf: `quality` -> `test` -> `build-deploy` (jeder Job nur bei Erfolg des
|
||||
vorherigen).
|
||||
Ablauf: `quality` -> `test` -> `publish` (jeder Job nur bei Erfolg des
|
||||
vorherigen). Der Job `publish` besteht aus drei Schritten: `actions/checkout@v4`
|
||||
mit `fetch-depth: 0` (volle Historie samt Tags, sonst liefert `git describe`
|
||||
nichts), Login in die Registry (siehe Abschnitt 3) und der Aufruf von
|
||||
`.gitea/scripts/publish-images.sh`.
|
||||
|
||||
### Kein Registry-Push
|
||||
### Zwei Kanaele: Etiketten je Anlass
|
||||
|
||||
Images werden **lokal auf dem Server gebaut** und nicht in eine Registry
|
||||
gepusht (D-13). Da der Runner und die Applikation auf demselben Server laufen,
|
||||
baut die Pipeline die Images direkt mit `docker compose build` und startet die
|
||||
Services mit `docker compose up -d` neu.
|
||||
Das Skript `.gitea/scripts/publish-images.sh` entscheidet allein anhand
|
||||
`GITHUB_REF`, ob und unter welchen Etiketten veroeffentlicht wird:
|
||||
|
||||
Vorteile:
|
||||
- Keine Registry-Infrastruktur noetig
|
||||
- Schnellerer Deploy (kein Push/Pull ueber Netzwerk)
|
||||
- Einfachere Konfiguration
|
||||
| Anlass | Kanal (`APP_CHANNEL`) | Etiketten in der Registry |
|
||||
|--------|----------------------|---------------------------|
|
||||
| Push auf `main` | `beta` | `beta` und `latest` (`latest` ist nur ein Alias fuer `beta` und entfaellt spaeter) |
|
||||
| Tag `vX.Y.Z` | `live` | `live` und `vX.Y.Z` |
|
||||
| Push auf `live` ohne Tag | -- | keine; der Lauf prueft nur (`quality`, `test`), das Skript endet mit "nichts zu tun" |
|
||||
|
||||
Das Kanalmodell fuer den Betrieb (welcher Server welches Etikett zieht, Freigabe,
|
||||
Hotfix) steht in `docs/anleitung-betrieb.md`, Kapitel 9.
|
||||
|
||||
### Versionsstempel
|
||||
|
||||
Das Skript berechnet vier Werte und gibt sie als `--build-arg` an beide
|
||||
Dockerfiles (`apps/web/Dockerfile`, `apps/api/Dockerfile`):
|
||||
|
||||
| Build-Arg | Quelle |
|
||||
|-----------|--------|
|
||||
| `APP_VERSION` | `git describe --tags --always` (ohne Tag: kurzer Commit-SHA) |
|
||||
| `APP_CHANNEL` | `beta` oder `live`, siehe Tabelle oben |
|
||||
| `APP_COMMIT` | `git rev-parse --short HEAD` |
|
||||
| `APP_BUILD_TIME` | `date -u`, ISO-Format |
|
||||
|
||||
Die API liest die Werte zur Laufzeit (`GET /health/version`, Startzeile im Log).
|
||||
Das Web-Image bettet `NEXT_PUBLIC_APP_*` beim Build in das Browser-Bundle ein --
|
||||
deshalb laeuft die `builder`-Stufe des Web-Images jetzt bei jedem Pipeline-Lauf
|
||||
neu, die Laufzeit liegt eher bei 4-6 statt 2 Minuten.
|
||||
|
||||
Lokale Probe ohne Docker-Aufruf:
|
||||
|
||||
```bash
|
||||
GITHUB_REF=refs/tags/v1.2.3 sh .gitea/scripts/publish-images.sh --print-plan
|
||||
```
|
||||
|
||||
Hinweis: Die fruehere Entscheidung D-13 (Images lokal bauen, keine Registry) ist
|
||||
ueberholt -- seit der Einfuehrung der Gitea-Registry werden Images gepusht und von
|
||||
den Servern per `docker compose pull` geholt.
|
||||
|
||||
## 5. Sicherheitshinweise
|
||||
|
||||
@@ -146,6 +194,12 @@ Workflow-Dateien in `.gitea/workflows/` werden direkt aus dem Repository
|
||||
geladen. Da nur vertrauenswuerdiger Code gepusht wird (D-11, Claude als
|
||||
einziger Committer), ist das Risiko einer manipulierten Pipeline minimal.
|
||||
|
||||
Ein Tag-Push `v*` ist der Freigabe-Hebel fuer Live: wer ihn setzen darf, kann
|
||||
das `live`-Etikett neu belegen. Heute hat nur das Konto `schalli` Schreibrecht
|
||||
(0 Kollaborateure, keine Branch-Regeln). Kommen weitere Konten dazu, in Gitea
|
||||
unter **Repository > Settings > Branches / Tags** eine Tag-Schutzregel fuer `v*`
|
||||
und einen Branch-Schutz fuer `live` anlegen (T-KU1-04).
|
||||
|
||||
## 6. Fehlerbehebung
|
||||
|
||||
### Runner registriert sich nicht
|
||||
@@ -167,3 +221,11 @@ einziger Committer), ist das Risiko einer manipulierten Pipeline minimal.
|
||||
erreichbar ist
|
||||
2. Docker Daemon Status pruefen: `docker info`
|
||||
3. Disk Space pruefen: `df -h`
|
||||
|
||||
### Stempel zeigt `dev` oder nur eine Kurzkennung statt des Tags
|
||||
|
||||
1. Im Job `publish` pruefen, dass `actions/checkout@v4` mit `fetch-depth: 0`
|
||||
auscheckt -- ohne Tags liefert `git describe --tags --always` nur den SHA
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user