213 lines
9.9 KiB
Markdown
213 lines
9.9 KiB
Markdown
# Kochwas — Deployment & Operations
|
||
|
||
## Deployment-Topologie
|
||
|
||
```
|
||
Browser
|
||
↓ HTTPS (kochwas.siegeln.net)
|
||
Cloudflare DNS (A-Record auf Pi-IP oder Tunnel)
|
||
↓
|
||
Raspberry Pi 5 (arm64, Debian/Ubuntu)
|
||
↓
|
||
Traefik v3 (Docker, Container "traefik" im Netz traefik_proxy)
|
||
↓ reverse proxy
|
||
Kochwas-Container (Node 22 Alpine, Port 3000, internal bridge)
|
||
↔ SearXNG-Container (Sidecar im gleichen Stack, Port 8080 intern)
|
||
```
|
||
|
||
- **Traefik** terminiert TLS mit Wildcard-Cert `*.siegeln.net` von Let's Encrypt (DNS-01 Challenge über Cloudflare-API).
|
||
- **SearXNG** läuft als Sidecar im kochwas-Compose. Kochwas spricht ihn über `http://searxng:8080` intern an.
|
||
- **Gitea Registry** `gitea.siegeln.net/claude/kochwas` hostet das arm64-Image.
|
||
- **Daten** liegen im Volume `/opt/docker/kochwas/data/` (SQLite + images/).
|
||
|
||
## Build & Publish (Gitea Actions)
|
||
|
||
Workflow in `.gitea/workflows/docker.yml`:
|
||
|
||
1. Trigger: push auf `main`
|
||
2. Checkout, Setup QEMU + Buildx
|
||
3. Login an `gitea.siegeln.net` mit Secret `REGISTRY_TOKEN` (PAT mit `write:package` + `read:package` Scope)
|
||
4. `docker/build-push-action` baut **nativ arm64** (nicht via emuliertem amd64!), mit `cache-from/to: type=registry,ref=...:buildcache`
|
||
5. Push als `:latest` und `:${commit}`
|
||
|
||
Wenn die Pipeline rot ist, häufig:
|
||
- `unauthorized`: Token fehlt oder ohne Package-Scope. PAT unter Gitea → Settings → Applications → Generate Token.
|
||
- Build-Cache i/o-Timeout: Registry-Cache benutzen, nicht GHA-Artifact-Cache.
|
||
|
||
## Deploy auf den Pi
|
||
|
||
```bash
|
||
ssh admin@pi5
|
||
cd /opt/docker/kochwas
|
||
docker compose -f docker-compose.prod.yml pull
|
||
docker compose -f docker-compose.prod.yml up -d
|
||
docker compose logs -f kochwas
|
||
```
|
||
|
||
Was der Pi braucht (einmalig):
|
||
- `/opt/docker/kochwas/docker-compose.prod.yml` — gespiegelt aus dem Repo
|
||
- `/opt/docker/kochwas/.env` mit `KOCHWAS_TAG=latest` (optional) und `SEARXNG_SECRET=...`
|
||
- `/opt/docker/kochwas/searxng/settings.yml` — aus dem Repo, mit `limiter: false` und `public_instance: false`
|
||
- `/opt/docker/kochwas/data/` existiert (für SQLite + images)
|
||
- Netzwerk `traefik_proxy` existiert, damit Traefik den Container sieht
|
||
|
||
## Traefik-Integration
|
||
|
||
Labels am kochwas-Container (siehe `docker-compose.prod.yml`):
|
||
|
||
```yaml
|
||
- traefik.enable=true
|
||
- traefik.docker.network=traefik_proxy
|
||
- traefik.http.routers.kochwas.rule=Host(`kochwas.siegeln.net`)
|
||
- traefik.http.routers.kochwas.entrypoints=websecure
|
||
- traefik.http.routers.kochwas.tls.certresolver=cloudflareResolver
|
||
- traefik.http.routers.kochwas.tls.domains[0].main=siegeln.net
|
||
- traefik.http.routers.kochwas.tls.domains[0].sans=*.siegeln.net
|
||
- traefik.http.services.kochwas.loadbalancer.server.port=3000
|
||
```
|
||
|
||
Die `tls.domains`-Zeilen sorgen dafür, dass der Router das Wildcard-Cert nutzt statt einen neuen per-Host-Cert zu holen. **Nie per-Host für neue Subdomains** — Let's Encrypt Rate-Limit (5 failed Authorizations pro Identifier pro Stunde, 50 Certs pro Registered Domain pro Woche).
|
||
|
||
### Wenn Cert fehlt / TLS-Fehler
|
||
|
||
1. `echo | openssl s_client -servername kochwas.siegeln.net -connect kochwas.siegeln.net:443 2>/dev/null | openssl x509 -noout -issuer -subject` — ist der Issuer „TRAEFIK DEFAULT CERT"? Dann hat Traefik kein Cert.
|
||
2. `sudo jq '.cloudflareResolver.Certificates | map(.domain.main)' /opt/docker/traefik/letsencrypt/acme.json` — ist `siegeln.net` (mit SAN `*.siegeln.net`) dabei?
|
||
3. `docker logs traefik 2>&1 | grep -iE 'lego|acme|cloudflare|kochwas' | tail -60` — Fehler?
|
||
- `Invalid access token` → Cloudflare-API-Token abgelaufen, neu erstellen mit `Zone → DNS → Edit` Scope, `CF_DNS_API_TOKEN` im Traefik-Compose setzen, `docker compose up -d traefik`
|
||
- `429 rateLimited` → Warten (zeitangabe im Error) oder auf Wildcard umstellen
|
||
|
||
## Troubleshooting
|
||
|
||
### Container läuft, Traefik filtert ihn raus
|
||
|
||
Symptom: Traefik-Logs sagen `Filtering unhealthy or starting container`.
|
||
Ursache: Healthcheck schlägt fehl. Der Check ruft `wget 127.0.0.1:3000/api/health` (muss IPv4 sein!).
|
||
|
||
```bash
|
||
docker inspect kochwas-kochwas-1 --format '{{json .State.Health}}' | jq
|
||
docker exec kochwas-kochwas-1 wget -qO- 127.0.0.1:3000/api/health
|
||
```
|
||
|
||
### SearXNG gibt 403 zurück
|
||
|
||
Log: `Internet-Suche zurzeit nicht möglich: HTTP 403`
|
||
Ursache: Bot-Detection. Fix war schon einmal nötig — `src/lib/server/http.ts` setzt via `extraHeaders` `X-Forwarded-For: 127.0.0.1` und `X-Real-IP: 127.0.0.1`. Wenn trotzdem 403: `searxng/settings.yml` prüfen:
|
||
|
||
```yaml
|
||
use_default_settings: true
|
||
server:
|
||
limiter: false
|
||
public_instance: false
|
||
secret_key: ${SEARXNG_SECRET:-dev-secret-change-in-prod}
|
||
search:
|
||
formats: [html, json]
|
||
```
|
||
|
||
Der Server-Container muss diese Datei per Volume Mount sehen. Nach Änderung: `docker compose restart searxng`.
|
||
|
||
### Thumbnail-Cache leeren
|
||
|
||
```bash
|
||
docker exec kochwas-kochwas-1 sqlite3 /data/kochwas.db 'DELETE FROM thumbnail_cache;'
|
||
```
|
||
|
||
Oder gezielt eine URL:
|
||
```bash
|
||
docker exec kochwas-kochwas-1 sqlite3 /data/kochwas.db \
|
||
"DELETE FROM thumbnail_cache WHERE url = 'https://www.chefkoch.de/rezepte/...';"
|
||
```
|
||
|
||
### Datenbank-Backup manuell
|
||
|
||
```bash
|
||
ssh admin@pi5 'docker exec kochwas-kochwas-1 sqlite3 /data/kochwas.db ".backup /data/backup.db"'
|
||
scp admin@pi5:/opt/docker/kochwas/data/backup.db ./kochwas-$(date +%F).db
|
||
```
|
||
|
||
Die App hat ein eingebautes Backup unter `/admin` (ZIP-Export mit DB + Bildern). Restore via `/admin` ebenfalls.
|
||
|
||
## Umgebungsvariablen
|
||
|
||
| Name | Default | Bedeutung |
|
||
|---|---|---|
|
||
| `SEARXNG_URL` | `http://localhost:8888` | SearXNG-Endpoint, im Compose auf `http://searxng:8080` |
|
||
| `KOCHWAS_THUMB_TTL_DAYS` | `30` | TTL für Thumbnail-Cache in der SQLite |
|
||
| `DATABASE_PATH` | `data/kochwas.db` | Pfad zur SQLite, relativ oder absolut |
|
||
| `IMAGE_DIR` | `data/images` | Pfad für lokale Bild-Dateien |
|
||
| `PORT` | `3000` | Node-HTTP-Port (adapter-node) |
|
||
|
||
Siehe `.env.example` im Repo.
|
||
|
||
## Häufige Commits als Referenz
|
||
|
||
- **Healthcheck-Fix** → `Dockerfile` (localhost → 127.0.0.1, tightened interval)
|
||
- **SearXNG-Bot-Bypass** → `src/lib/server/http.ts` (extraHeaders)
|
||
- **Traefik-Wildcard** → `docker-compose.prod.yml` (tls.domains Labels)
|
||
- **Thumbnail-Cache in SQLite** → `003_thumbnail_cache.sql` + `searxng.ts`
|
||
|
||
Git-Log ist die Wahrheit; diese Datei ist eine Orientierung.
|
||
|
||
## PWA / Offline-Modus
|
||
|
||
Kochwas ist eine installierbare PWA. Erkennbar an:
|
||
- `static/manifest.webmanifest` (Manifest + Icons: SVG + 192×192 + 512×512, alle maskable)
|
||
- `src/service-worker.ts` (Cache + Sync)
|
||
|
||
Caches im Browser (siehe DevTools → Application → Cache Storage):
|
||
- `kochwas-shell-<version>` — App-Shell (JS/CSS/Static-Icons), cache-first
|
||
- `kochwas-data-v1` — Rezept-HTMLs + API-JSON (network-first, 3 s Timeout → Cache-Fallback)
|
||
- `kochwas-images-v1` — Bilder (cache-first)
|
||
- `kochwas-meta` — Cache-Manifest (Liste der gecachten Rezept-IDs unter `/__cache-manifest__`)
|
||
|
||
Sync-Verhalten:
|
||
- **Initial-Sync** (nach erstem Install): SW lädt alle Rezepte + Bilder im Hintergrund. Fortschritt im `SyncIndicator`-Pill unten rechts.
|
||
- **Update-Sync** (bei jedem App-Start online): Diff gegen Cache-Manifest, nur Delta nachladen, gelöschte IDs räumen.
|
||
- **Storage-Quota-Check**: < 100 MB frei → abbrechen mit Fehler-Toast.
|
||
|
||
Bei SW-Problemen Debug-Pfad:
|
||
1. Admin → „App"-Tab → „Offline-Cache leeren" (destructive, zweistufig bestätigt)
|
||
2. Alternative: DevTools → Application → Service Workers → Unregister, dann Seite neu laden.
|
||
|
||
E2E-Tests (Playwright): `npm run test:e2e`. Setzt `npm run build` voraus (Playwright startet automatisch `npm run preview`).
|
||
|
||
Icons einmalig rendern: `npm run render:icons` (schreibt nach `static/icon-*.png`, committen).
|
||
|
||
## Dev-System / Remote-E2E
|
||
|
||
`https://kochwas-dev.siegeln.net/` ist ein separates Deployment (eigener Container, eigene DB unter `/opt/docker/kochwas-dev/data/`). Zweck: E2E-Tests gegen eine prod-nahe Umgebung ohne Angst vor DB-Schäden. Die Remote-Suite (`tests/e2e/remote/`, Config `playwright.remote.config.ts`) darf dort frei CRUDen — User stellt die DB bei Bedarf per Backup wieder her.
|
||
|
||
```bash
|
||
npm run test:e2e:remote # gegen kochwas-dev
|
||
E2E_REMOTE_URL=https://... npm run test:e2e:remote # andere URL
|
||
```
|
||
|
||
Wichtige Config-Eigenschaften:
|
||
- `workers: 1` — DB-Race-Sicherheit bei CRUD-Tests.
|
||
- `serviceWorkers: 'block'` — verhindert Chromium-Crashes durch akkumulierten SW-State über 40+ Contexts.
|
||
- Fixtures unter `tests/e2e/remote/fixtures/`: `profile.ts` (Profile-Auswahl via localStorage vor Seitenladen), `api-cleanup.ts` (idempotente DELETE-Helfer für afterEach).
|
||
|
||
**Niemals gegen `kochwas.siegeln.net` (ohne `-dev`)** die destruktiven Tests laufen lassen — das ist Prod.
|
||
|
||
|
||
## Gemini / Foto-Rezept-Magie
|
||
|
||
Die Funktion „Foto → Rezept" ruft Google Gemini 2.5 Flash mit Vision auf. Im Header erscheint dann ein Kamera-Icon, das auf `/new/from-photo` führt.
|
||
|
||
**Env-Vars** (in `docker-compose.prod.yml`):
|
||
|
||
| Variable | Default | Zweck |
|
||
|---|---|---|
|
||
| `GEMINI_API_KEY` | _(leer)_ | Ohne Key ist das Feature graceful deaktiviert — Camera-Icon erscheint nicht. |
|
||
| `GEMINI_MODEL` | `gemini-2.5-flash` | Modell-Wechsel ohne Rebuild, z. B. auf `gemini-2.5-pro` bei harter Handschrift. |
|
||
| `GEMINI_TIMEOUT_MS` | `20000` | Timeout für den Vision-Call. |
|
||
|
||
**Wichtig:** Env-Änderungen greifen erst nach `docker compose up -d --force-recreate`, nicht nach `restart`.
|
||
|
||
**Privacy:** Das hochgeladene Foto geht einmal an Google Gemini und wird serverseitig nicht gespeichert. Google trainiert im Paid-Tier nicht auf API-Daten. Der Server loggt nur Status-Code, Dauer und Bildgröße — nie Prompt oder Response-Inhalt.
|
||
|
||
**Rate-Limit:** 10 Requests/Minute pro IP (in-memory, resettet beim Prozess-Restart).
|
||
|
||
**Key aus Gitea Secrets:** `GEMINI_API_KEY` als Secret in der CI-Umgebung hinterlegen; der Deploy-Schritt injiziert ihn in die `.env` des Pi-Stacks. Ablauf-Monitoring über die Google-Cloud-Konsole (≥1× pro Quartal checken).
|
||
|
||
**Build-Dep `sharp`:** Der Foto-Preprocess nutzt `sharp` (libvips). Im `Dockerfile`-Builder-Stage ist `vips-dev` enthalten, damit der npm-install auf arm64 sauber durchläuft — insbesondere für HEIC-Input von iOS-Geräten (libheif kommt via vips-dev).
|