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

20 KiB

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:
        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

  • ASSET_CDN_URL-Env-Var konfigurierbar; Vite-Build nutzt sie für asset-base
  • Cache-Control-Headers gesetzt für /assets/* (immutable 1y), /fonts/*+/images/* (1d)
  • Bunny.net-Setup-Steps in docs/ops/asset-cdn.md dokumentiert
  • Cloudflare-Setup als Alternative dokumentiert
  • CI-Post-Deploy-Purge-Step funktioniert (skip wenn BUNNY_PULL_ZONE_ID/BUNNY_API_KEY fehlen)
  • Lokales Dev funktioniert unverändert (kein CDN-Detour in Dev-Mode)
  • Image-Optimization-Opt-In dokumentiert
  • 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)
  • 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:

    # 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.)