# 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//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 `