Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/03-scaling-infrastructure/asset-cdn.md
T

314 lines
20 KiB
Markdown

# Asset-CDN vor static assets
**Status:** implementation landed; provider provisioning and `ASSET_CDN_URL`
rollout remain backlogged/operator-deferred with A7/B2/#51.
**Task-ID:** #51
**Phase:** 03
**Estimated Effort:** 1-2 Tage
**Owner:** unassigned
## Current Truth
This detail plan is historical implementation context. The code-side CDN
preparation has landed: `ASSET_CDN_URL` feeds the Vite asset base, static asset
headers are served by `server/server.ts`, and the deploy workflow includes a
no-op-safe Bunny purge step. The remaining work is provider provisioning,
environment flips, and staging/production verification; A7/B2/#51 intentionally
remain parked/backlog.
Original motivation:
- **App-Server bedient Asset-Requests** → unnötige CPU/Bandwidth-Last; First-Page-Load schickt 1-3 MB JS+CSS pro neuem Visitor durch den Origin.
- **Latency global ungleich:** User in den USA holen sich ein Bundle aus dem Hetzner-Frankfurt-DC → 100+ ms RTT vs. 10-30 ms via CDN-PoP.
- **Cache-Control-Headers fehlten oder waren zu konservativ:** fixed for static
server paths; keep this item as historical motivation, not a current defect.
- **Skalierungs-Schmerz beim Traffic-Spike:** Marketing-Aktion bringt 10k Visitors gleichzeitig auf die Landing-Page → Origin muss alle JS-Bundles N-mal ausliefern statt einmal an CDN.
- **Image-Optimization fehlt:** User-Uploads (Avatars, Tenant-Logos, Email-Marketing-Bilder) werden in Originalgröße ausgeliefert; kein WebP/AVIF, kein Resize.
Betroffene Codestellen:
- `server/server.ts` — static asset `Cache-Control` headers
- `apps/web/app/entry.server.tsx` — SSR HTML `no-store` default
- `apps/web/vite.config.ts` — Asset-Prefix-Config
- `apps/web/public/` — Static-Assets
- Build-Output: `apps/web/build/client/assets/`
## Depends on
- `01-tech-debt-foundation/dep-updates.md` — Vite-Version aktuell genug damit `build.base`/`base`-Config zuverlässig funktioniert.
- `02-observability/performance-quickwins.md` — Performance-Baseline-Metrics (LCP, TTFB) damit man CDN-Improvement messen kann.
## Blocks
- `08-mobile-cli-storybook-sdk/storybook.md` — Storybook-Build kann optional von gleicher CDN-Strategie profitieren; soft-dependency.
- `10-compliance-polish/lighthouse.md` — Lighthouse-Score-Improvements durch CDN sind Teil der Polish-Phase-Audits.
## Approach
**Bunny.net als Default-Empfehlung, Cloudflare als dokumentierte Alternative.**
**Begründung Bunny.net:**
- **EU-basiert** (Slowenien) — DSGVO-freundlich, keine Schrems-II-Issues für EU-only-Tenants.
- **Sehr günstig:** ~€1-5/Monat für kleine SaaS, kein Verschleier-Pricing.
- **Origin-Pull einfach:** Pull-Zone-Setup in 5 Min, kein DNS-Hijacking nötig (nur CNAME für CDN-Subdomain).
- **Image-Optimizer als Add-On:** „Bunny Optimizer" für $9.50/Mo (optional, später aktivierbar).
- **API für Cache-Purge:** ergonomisch.
**Cloudflare als Alternative:**
- Wenn Operator schon Cloudflare-DNS nutzt, ist Integration trivial.
- Free-Tier reicht für kleine Sites.
- Image-Optimization via Cloudflare-Images ($5/Mo + Usage).
- Nachteile: US-HQ (DSGVO-Komplexität für strikte EU-Kunden), aggressive Default-Caching kann unintended Behavior triggern, DNS muss zu Cloudflare migriert werden für volle Features.
**Architektur:**
```
Browser
│
├─→ cdn.{domain}/assets/app-3f4a1b.js ──→ Bunny.net CDN (cache hit: 1ms)
│ │
│ └─ origin pull: app.{domain}/assets/app-3f4a1b.js
│ │
│ └─ React Router server returns asset with Cache-Control: public, max-age=31536000, immutable
│
└─→ app.{domain}/... ──→ App-Server direkt (HTML, API)
```
**Vite-Konfiguration:** `build.base = process.env.ASSET_CDN_URL ?? '/'`. Lokal/Dev: `/` (kein CDN). Staging/Production: `https://cdn-staging.{domain}` / `https://cdn.{domain}`.
**Cache-Strategie:**
- `/assets/*` (Vite-hashed): `Cache-Control: public, max-age=31536000, immutable` — 1 Jahr, immutable wegen Hash-Naming.
- `/fonts/*`, `/images/*` (statische Brand-Assets): `Cache-Control: public, max-age=86400` — 1 Tag, weil nicht hash-named.
- HTML-Responses: `Cache-Control: no-store` (oder kurzes max-age für Marketing-Pages explizit).
- `/uploads/*` (User-Content über `apps/web/app/routes/uploads.tsx` oder ähnlich, falls existent): `Cache-Control: private, max-age=300` (5 Min, weil PII-relevant; Bunny darf cachen wenn separate Upload-CDN-Zone für Public-Uploads).
**Cache-Purge bei Deploy:** Bunny-Pull-Zone-API-Call nach jedem erfolgreichen Deploy invalidate-d die ganze Zone (oder nur `/assets/*`). Implementiert als CI-Step in der Deploy-Pipeline.
**Image-Optimization-Layer (optional, Phase-2-Activate):** Bunny-Optimizer als Add-On für `/uploads/*` — automatisches WebP-Negotiation, Resize via URL-Params (`?width=400&format=webp`). Nicht initial aktivieren, dokumentieren wann sinnvoll (wenn mehr als ~10 GB Image-Traffic/Monat).
**Begründung gegen Alternativen:**
- _AWS CloudFront:_ funktional, aber teurer pro Bandwidth, US-only-Anbieter-Optik problematisch für manche EU-Kunden.
- _Nginx-Reverse-Proxy mit Cache als Self-Hosted-CDN:_ nur ein PoP, kein globaler Edge-Effekt. Nur sinnvoll wenn Operator dedizierten Reason hat CDN-Provider zu vermeiden.
- _Kein CDN:_ Status-Quo, blockt Skalierung und Performance.
## Implementation Steps
1. **Vite-Config: ASSET_CDN_URL-Switch** — `build.base` aus Env
- Files: `apps/web/vite.config.ts` (Edit) — `base: process.env.ASSET_CDN_URL ? new URL('/assets/', process.env.ASSET_CDN_URL).toString() : '/'`. Dev-Mode: immer `/` (kein CDN-Detour).
- Tests: `apps/web/vite.config.test.ts` — assert mit/ohne Env-Var korrekte `base`-Werte.
- Commit: `03-scaling/asset-cdn: vite base config from ASSET_CDN_URL env`
2. **Cache-Control-Header in static server + HTML entry** — pro Pfad-Pattern Headers setzen
- Files: `server/server.ts` (static directories) and
`apps/web/app/entry.server.tsx` (SSR HTML default)
- Tests: `server/server.test.ts` and `apps/web/app/entry.server.test.ts`
- Commit: `03-scaling/asset-cdn: cache-control headers per asset pattern`
3. **Asset-Pfad-Konsistenz prüfen** — kein hardcoded `/assets/`-Prefix in Code
- Files: Audit via Grep, alle Stellen die Assets direkt referenzieren. React-Router-Routen sollten Asset-URLs aus `import.meta.url` oder Vite's `import asset from "..."` Pattern beziehen (das nutzt automatisch `base`).
- Commit: `03-scaling/asset-cdn: ensure all asset paths use vite base resolution` (falls Changes nötig)
4. **Bunny.net-Setup-Doku** — Step-by-Step für Operator
- Files: `docs/ops/asset-cdn.md` — Sektionen:
- Provider-Vergleich (Bunny vs Cloudflare; warum Bunny Default)
- Bunny-Setup:
1. Account anlegen, Payment-Methode hinzufügen
2. Pull-Zone erstellen: `cdn-{env}-{domain}`, Origin URL = `https://app-{env}.{domain}`, Pull-Headers konfigurieren.
3. Custom-Hostname: `cdn.{domain}` mit DNS-CNAME → `cdn-{env}-{domain}.b-cdn.net`
4. Edge-Rules: bypass cache für `/api/*` und `/healthz`, force cache für `/assets/*` (override Origin wenn nötig)
5. SSL: automatisch via Let's Encrypt
6. API-Key generieren für Purge-Calls
7. Env-Var `ASSET_CDN_URL=https://cdn.{domain}` setzen
- Cloudflare-Setup als Alternative (kürzer):
1. DNS zu CF migrieren (oder nur Subdomain `cdn.{domain}` als CNAME)
2. Page-Rules für Cache-Verhalten
3. Cache-API-Token erstellen
- Cache-Purge-API-Beispiel:
```bash
curl -X POST "https://api.bunny.net/pullzone/<id>/purgeCache" \
-H "AccessKey: ${BUNNY_API_KEY}"
```
- Image-Optimizer-Setup (Phase 2, optional)
- Troubleshooting (Origin-Loop, 502er, Stale-Cache)
- Commit: `03-scaling/asset-cdn: cdn operations doc`
5. **CI-Cache-Purge-Step** — nach Deploy ausführen
- Files: `.gitea/workflows/deploy.yml` und `scripts/cdn/bunny-purge.ts` — Post-Deploy-Step nutzt Bunny-Purge-API. Env-Vars: `BUNNY_PULL_ZONE_ID`, `BUNNY_API_KEY` (in CI-Secrets).
- Wenn `ASSET_CDN_URL` nicht gesetzt → Step skip (kein-CDN-Mode).
- Commit: `03-scaling/asset-cdn: ci post-deploy cdn purge step`
6. **Lokales Dev-Verhalten dokumentieren** — kein CDN in Dev
- Files: `apps/web/README.md` (Edit) oder `docs/development/local-setup.md` — Hinweis dass `ASSET_CDN_URL` lokal leer bleibt, Assets aus Vite-Dev-Server.
- Commit: `03-scaling/asset-cdn: document local dev behavior`
7. **Image-Optimization-Hinweis (nicht implementieren, nur dokumentieren)** — Phase-2-Aktivierung
- Files: `docs/ops/asset-cdn.md` — eigene Sektion „When to enable Image Optimization". Trigger-Criteria: ≥ 10 GB Image-Bandwidth/Mo, ≥ 1k Image-Uploads/Mo, Lighthouse-Score < 80 wegen Bildgrößen. Bunny-Optimizer-Setup-Schritte.
- Commit: `03-scaling/asset-cdn: document image optimization opt-in`
## Test Requirements
- **Unit-Tests:**
- `apps/web/vite.config.test.ts` — `base`-Wert mit/ohne `ASSET_CDN_URL` korrekt.
- `server/server.test.ts` — Cache-Control-Headers per static path pattern.
- `apps/web/app/entry.server.test.ts` — HTML no-store default.
- **Integration-Tests:** keine spezifischen — CDN ist External-Service, kann nicht in CI gemockt werden ohne Aufwand. Stattdessen Staging-Verifikation.
- **E2E (Playwright):** existing E2E-Suite läuft gegen Staging (mit CDN aktiv) → assert keine Regression. Asset-Requests in Network-Tab sollten auf `cdn.staging.{domain}` zeigen.
- **Coverage-Target:** ≥ 90% für `entry.server.tsx`-Header-Logic; vite.config muss nicht abgedeckt sein (declarative).
- **Test-Files:** wie aufgelistet.
**NICHT als completed markieren bevor alle Tests grün sind.**
## Acceptance Criteria
- [x] `ASSET_CDN_URL`-Env-Var konfigurierbar; Vite-Build nutzt sie für asset-base
- [x] Cache-Control-Headers gesetzt für `/assets/*` (immutable 1y), `/fonts/*`+`/images/*` (1d)
- [x] Bunny.net-Setup-Steps in `docs/ops/asset-cdn.md` dokumentiert
- [x] Cloudflare-Setup als Alternative dokumentiert
- [x] CI-Post-Deploy-Purge-Step funktioniert (skip wenn `BUNNY_PULL_ZONE_ID`/`BUNNY_API_KEY` fehlen)
- [x] Lokales Dev funktioniert unverändert (kein CDN-Detour in Dev-Mode)
- [x] Image-Optimization-Opt-In dokumentiert
- [x] Tests grün (source-level unit coverage)
- [ ] Staging-Verifikation: Asset-Requests gehen zu Bunny-PoP, Cache-Hit-Ratio > 80% nach Warm-Up; LCP-Improvement messbar (Lighthouse vor/nach)
- [x] Detail-MD Progress Log aktualisiert
- [ ] `PROGRESS.md` hält #51 im Backlog, bis A7/B2 reaktiviert sind und die Staging-CDN-Verifikation bestanden hat
## Rollback Strategy
- **Sofort-Rollback:** `ASSET_CDN_URL` aus Env entfernen → nächster Build deployed mit Origin-Asset-Pfaden. Browser-Cache von alten CDN-URLs wird ausgegrast (max 1 Jahr für `immutable`-Assets — Mitigation: HTML enthält die neuen Origin-Pfade nach Rollback-Build, alte CDN-Pfade werden nicht mehr referenziert).
- **DNS-Rollback:** `cdn.{domain}`-CNAME entfernen → Browser können CDN nicht mehr erreichen. Risiko: User die mitten in einer Session sind, sehen Asset-Loading-Errors. Mitigation: Rollback in CI = ASSET_CDN_URL entfernen statt DNS anpacken.
- **Cache-Control-Issue:** Wenn falscher Cache-Control deployed wird (z.B. `immutable` auf falsches Pattern) — Purge via Bunny-API + Korrektur-Deploy. Aggressives Caching kann mehrere Stunden Stale-State verursachen falls Purge fehlschlägt.
- **Feature-Flag:** kein dedizierter Flag nötig — `ASSET_CDN_URL`-Env-Var ist der Flag.
## Security Notes
- **CDN-as-MITM-Risk:** Bunny/Cloudflare sehen alle Asset-Requests inkl. Referrer-Headers. Für Static-Assets ohne PII unkritisch; Image-Uploads mit potentiell PII (User-Avatars) sollten in Sub-Zone mit strikteren Privacy-Settings (oder gar nicht über CDN gehen — `/uploads/*` als `private` markiert verhindert Public-Edge-Caching).
- **CORS:** Falls App-Server Fonts/Bilder über CDN ausliefert und JS sie via fetch lädt → CORS-Headers konfigurieren (`Access-Control-Allow-Origin: https://app.{domain}`). Bunny passt das durch; Origin-Server muss korrekt setzen.
- **CSP:** Content-Security-Policy muss CDN-Hostname als `script-src`/`style-src`/`font-src`/`img-src` whitelist haben. Existierende CSP-Konfiguration prüfen und CDN-Host ergänzen (in `apps/web/app/entry.server.tsx` oder middleware).
- **Subresource-Integrity (SRI):** Vite kann SRI-Hashes für `<script>`-Tags generieren — empfohlen wenn CDN-Risiko-Modell hoch ist (Operator wechselt CDN-Provider, fremde Skripte könnten injiziert werden). Initial nicht aktivieren (Performance-Kosten), aber dokumentieren.
- **Origin-Schutz:** Bunny erlaubt „Origin Shield" + IP-Whitelist (nur Bunny-IPs dürfen Origin pullen). Empfehlen in Setup-Doku — verhindert dass Angreifer Origin direkt hämmern und CDN umgehen.
- **Cache-Poisoning:** CDN cached basierend auf URL + Vary-Headers. Wenn App-Server vergisst `Vary: Authorization` für Authed-Endpoints zu setzen, könnten Authed-Responses gecached und an andere User ausgeliefert werden. Mitigation: Nur `/assets/*`, `/fonts/*`, `/images/*` werden gecacht; alles andere `Cache-Control: no-store` oder `private`.
## Subagent Recommendations
- **Planning:** `Plan`-Subagent mit Detail-MD; recherchiert ob `apps/web/vite.config.ts` schon eine `base`-Config hat und ob `entry.server.tsx` existing Cache-Header-Logic enthält.
- **Research:** `Explore`-Subagent für Bunny.net-API-Docs aktuelle Pull-Zone-Schritte (CDN-Provider-APIs ändern sich) — verifizieren bevor Doku finalized wird.
- **Implementation:** `general-purpose`-Subagent für Steps 1-3 (Code-Changes), separater für Doku-Steps 4-7.
- **Tests:** `general-purpose`-Subagent für die zwei Unit-Test-Files.
- **Verification:** `gsd-verifier`-Subagent gegen Acceptance-Criteria; manuelle Staging-Verifikation der CDN-Connectivity.
- **Code-Review:** `gsd-code-reviewer` nach Phasen-Abschluss; Security-Track-Subagent prüft CSP-/CORS-Implikationen.
## Staging-Deployment-Steps
Historical runbook only while #51 is backlogged. Do not treat these as active
operator steps unless `PROGRESS.md` and `OPERATOR-CHECKLIST.md` reactivate the
CDN rollout triggers.
1. Branch `agent/03-asset-cdn` pushen.
2. Bunny.net-Account vom Operator anlegen lassen (1x manuell — kann nicht automatisiert werden ohne API-Account).
3. Bunny-Setup auf Staging:
- Pull-Zone `cdn-staging-toolctrl` mit Origin `https://staging.toolctrl.de`
- Custom-Hostname `cdn-staging.toolctrl.de` mit DNS-CNAME
- Edge-Rule: bypass cache for `/api/*` und `/healthz`
- API-Key generieren, in Staging-Coolify als Env hinzufügen: `BUNNY_PULL_ZONE_ID`, `BUNNY_API_KEY`
4. Staging-Env-Variable setzen: `ASSET_CDN_URL=https://cdn-staging.toolctrl.de`
5. Coolify-Auto-Deploy.
6. Smoke-Tests:
```bash
# 1. Asset wird über CDN ausgeliefert
curl -I https://cdn-staging.toolctrl.de/assets/app-<hash>.js
# → expect: HTTP/2 200, server: BunnyCDN, x-cache: HIT (after warm-up)
# 2. Cache-Control korrekt
# → expect: cache-control: public, max-age=31536000, immutable
# 3. HTML wird NICHT über CDN ausgeliefert
curl -I https://staging.toolctrl.de/
# → server: not BunnyCDN, cache-control: no-store
# 4. Lighthouse-Score-Vergleich
lighthouse https://staging.toolctrl.de --output html --output-path ./before.html
# vorher (ohne CDN) und nachher (mit CDN) — LCP-Verbesserung erwartet
# 5. Purge-Test
curl -X POST "https://api.bunny.net/pullzone/${BUNNY_PULL_ZONE_ID}/purgeCache" \
-H "AccessKey: ${BUNNY_API_KEY}"
# → expect: 204 No Content
```
7. CSP-Check: Browser-DevTools-Console darf keine CSP-Violations zeigen.
8. Network-Tab im Browser: Asset-Requests gehen zu `cdn-staging.toolctrl.de`, nicht zu `staging.toolctrl.de`.
9. Production-Setup analog (eigene Pull-Zone, `cdn.toolctrl.de`-Hostname) — separater Deploy-Schritt vom Operator.
## Deviations from Plan
- **Cache-header file:** the spec assumed `entry.server.tsx` would set the
`/assets/*`, `/fonts/*`, `/images/*` headers. In practice the SSR entry
only renders HTML — static directories are served by `server/server.ts`
(`getStaticHeaders`). The `Cache-Control` rules for those directories
therefore live in `server/server.ts`; `entry.server.tsx` only adds the
`Cache-Control: no-store` default for HTML documents.
- **`base` literal:** the spec's literal `new URL('/assets/', ASSET_CDN_URL)`
would have produced `https://cdn.../assets/`, which Vite then prepends a
second `/assets/` to. Implemented as `<origin>/` instead so Vite controls
the `assets/` subdirectory exactly as it does for the origin build.
- **Path-scoped purge support:** added a `--paths` flag to the helper script
beyond the spec, so future hot-fix deploys can invalidate one bundle
instead of cold-missing the whole zone.
- **No `/uploads/*` handler yet:** the spec's `Cache-Control: private, max-age=300`
rule for `/uploads/*` has no implementation site today (no public
uploads route is wired into the static server). When uploads ship,
extend `server/server.ts:getStaticHeaders` to add that case.
## Progress Log
- **2026-05-17 — `03-scaling/asset-cdn: wire vite base from ASSET_CDN_URL env`**
Added `apps/web/app/utils/build/assetCdnBase.ts` (pure helper, no Vite
plugin imports) and consumed it from `apps/web/vite.config.ts`. Vite
build with the env var injects the CDN origin into asset URLs; build
without the env var keeps origin-relative paths. 8 unit tests cover
dev-mode bypass, malformed URLs, trailing-slash variants, and path
stripping.
- **2026-05-17 — `03-scaling/asset-cdn: set cache-control headers per asset pattern`**
Extended `server/server.ts:getStaticHeaders` so `/fonts/*` and
`/images/*` get `public, max-age=86400`; `/assets/*` already had the
`immutable` rule. `apps/web/app/entry.server.tsx` now defaults HTML
documents to `Cache-Control: no-store` (loaders can override).
Source-level tests in `server/server.test.ts` + `entry.server.test.ts`.
- **2026-05-17 — `03-scaling/asset-cdn: add cache-purge helper script`**
`scripts/cdn/bunny-purge.ts` wraps Bunny's purge API. Whole-zone or
per-path purges, fetch-injectable for tests, exits 0 when credentials
are absent so the deploy step can be wired before zone provisioning.
18 unit tests with a mocked fetch (error + success paths, argv parsing).
- **2026-05-17 — `03-scaling/asset-cdn: add cdn-purge step to deploy workflow`**
`.gitea/workflows/deploy.yml` now runs the purge after the Sentry
release marker; the step inline-skips when `BUNNY_API_KEY` is unset.
- **2026-05-17 — `03-scaling/asset-cdn: document cdn setup and provider alternatives`**
Authored `docs/ops/asset-cdn.md` covering Bunny.net setup, Cloudflare
alternative, cache strategy table, smoke tests, rollback, image
optimisation opt-in triggers, and security/CSP/CORS notes.
- **2026-05-17 — `03-scaling/asset-cdn: env vars in catalog and example`**
Added `ASSET_CDN_URL`, `BUNNY_PULL_ZONE_ID`, `BUNNY_API_KEY` to
`packages/config/src/catalog.ts` and `.env.example`. Env-drift contract
passes.
- **Outstanding (operator-owned):**
1. Provision Bunny.net pull zones (staging + production) per the
runbook in `docs/ops/asset-cdn.md`.
2. Add `BUNNY_PULL_ZONE_ID` + `BUNNY_API_KEY` as Gitea secrets and
Coolify env vars.
3. Set `ASSET_CDN_URL` in Coolify for `staging` + `production` deploy
targets.
4. Run the smoke tests in the runbook against staging.
5. Lighthouse before/after comparison so LCP improvement is recorded
against the acceptance criteria.
These steps are currently parked with A7/B2; the task remains
`backlog (operator-deferred 2026-05-24)` until CDN rollout is reactivated.
## Lessons Learned
(Optional am Task-Ende.)