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 assetCache-Controlheadersapps/web/app/entry.server.tsx— SSR HTMLno-storedefaultapps/web/vite.config.ts— Asset-Prefix-Configapps/web/public/— Static-Assets- Build-Output:
apps/web/build/client/assets/
Depends on
01-tech-debt-foundation/dep-updates.md— Vite-Version aktuell genug damitbuild.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 überapps/web/app/routes/uploads.tsxoder ä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
-
Vite-Config: ASSET_CDN_URL-Switch —
build.baseaus 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 korrektebase-Werte. - Commit:
03-scaling/asset-cdn: vite base config from ASSET_CDN_URL env
- Files:
-
Cache-Control-Header in static server + HTML entry — pro Pfad-Pattern Headers setzen
- Files:
server/server.ts(static directories) andapps/web/app/entry.server.tsx(SSR HTML default) - Tests:
server/server.test.tsandapps/web/app/entry.server.test.ts - Commit:
03-scaling/asset-cdn: cache-control headers per asset pattern
- Files:
-
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.urloder Vite'simport asset from "..."Pattern beziehen (das nutzt automatischbase). - Commit:
03-scaling/asset-cdn: ensure all asset paths use vite base resolution(falls Changes nötig)
- Files: Audit via Grep, alle Stellen die Assets direkt referenzieren. React-Router-Routen sollten Asset-URLs aus
-
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:
- Account anlegen, Payment-Methode hinzufügen
- Pull-Zone erstellen:
cdn-{env}-{domain}, Origin URL =https://app-{env}.{domain}, Pull-Headers konfigurieren. - Custom-Hostname:
cdn.{domain}mit DNS-CNAME →cdn-{env}-{domain}.b-cdn.net - Edge-Rules: bypass cache für
/api/*und/healthz, force cache für/assets/*(override Origin wenn nötig) - SSL: automatisch via Let's Encrypt
- API-Key generieren für Purge-Calls
- Env-Var
ASSET_CDN_URL=https://cdn.{domain}setzen
- Cloudflare-Setup als Alternative (kürzer):
- DNS zu CF migrieren (oder nur Subdomain
cdn.{domain}als CNAME) - Page-Rules für Cache-Verhalten
- Cache-API-Token erstellen
- DNS zu CF migrieren (oder nur Subdomain
- 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
- Files:
-
CI-Cache-Purge-Step — nach Deploy ausführen
- Files:
.gitea/workflows/deploy.ymlundscripts/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_URLnicht gesetzt → Step skip (kein-CDN-Mode). - Commit:
03-scaling/asset-cdn: ci post-deploy cdn purge step
- Files:
-
Lokales Dev-Verhalten dokumentieren — kein CDN in Dev
- Files:
apps/web/README.md(Edit) oderdocs/development/local-setup.md— Hinweis dassASSET_CDN_URLlokal leer bleibt, Assets aus Vite-Dev-Server. - Commit:
03-scaling/asset-cdn: document local dev behavior
- Files:
-
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
- Files:
Test Requirements
- Unit-Tests:
apps/web/vite.config.test.ts—base-Wert mit/ohneASSET_CDN_URLkorrekt.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.mddokumentiert - Cloudflare-Setup als Alternative dokumentiert
- CI-Post-Deploy-Purge-Step funktioniert (skip wenn
BUNNY_PULL_ZONE_ID/BUNNY_API_KEYfehlen) - 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.mdhält #51 im Backlog, bis A7/B2 reaktiviert sind und die Staging-CDN-Verifikation bestanden hat
Rollback Strategy
- Sofort-Rollback:
ASSET_CDN_URLaus Env entfernen → nächster Build deployed mit Origin-Asset-Pfaden. Browser-Cache von alten CDN-URLs wird ausgegrast (max 1 Jahr fürimmutable-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.
immutableauf 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/*alsprivatemarkiert 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-srcwhitelist haben. Existierende CSP-Konfiguration prüfen und CDN-Host ergänzen (inapps/web/app/entry.server.tsxoder 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: Authorizationfür Authed-Endpoints zu setzen, könnten Authed-Responses gecached und an andere User ausgeliefert werden. Mitigation: Nur/assets/*,/fonts/*,/images/*werden gecacht; alles andereCache-Control: no-storeoderprivate.
Subagent Recommendations
- Planning:
Plan-Subagent mit Detail-MD; recherchiert obapps/web/vite.config.tsschon einebase-Config hat und obentry.server.tsxexisting 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-reviewernach 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.
-
Branch
agent/03-asset-cdnpushen. -
Bunny.net-Account vom Operator anlegen lassen (1x manuell — kann nicht automatisiert werden ohne API-Account).
-
Bunny-Setup auf Staging:
- Pull-Zone
cdn-staging-toolctrlmit Originhttps://staging.toolctrl.de - Custom-Hostname
cdn-staging.toolctrl.demit 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
- Pull-Zone
-
Staging-Env-Variable setzen:
ASSET_CDN_URL=https://cdn-staging.toolctrl.de -
Coolify-Auto-Deploy.
-
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 -
CSP-Check: Browser-DevTools-Console darf keine CSP-Violations zeigen.
-
Network-Tab im Browser: Asset-Requests gehen zu
cdn-staging.toolctrl.de, nicht zustaging.toolctrl.de. -
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.tsxwould set the/assets/*,/fonts/*,/images/*headers. In practice the SSR entry only renders HTML — static directories are served byserver/server.ts(getStaticHeaders). TheCache-Controlrules for those directories therefore live inserver/server.ts;entry.server.tsxonly adds theCache-Control: no-storedefault for HTML documents. baseliteral: the spec's literalnew URL('/assets/', ASSET_CDN_URL)would have producedhttps://cdn.../assets/, which Vite then prepends a second/assets/to. Implemented as<origin>/instead so Vite controls theassets/subdirectory exactly as it does for the origin build.- Path-scoped purge support: added a
--pathsflag 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'sCache-Control: private, max-age=300rule for/uploads/*has no implementation site today (no public uploads route is wired into the static server). When uploads ship, extendserver/server.ts:getStaticHeadersto add that case.
Progress Log
- 2026-05-17 —
03-scaling/asset-cdn: wire vite base from ASSET_CDN_URL envAddedapps/web/app/utils/build/assetCdnBase.ts(pure helper, no Vite plugin imports) and consumed it fromapps/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 patternExtendedserver/server.ts:getStaticHeadersso/fonts/*and/images/*getpublic, max-age=86400;/assets/*already had theimmutablerule.apps/web/app/entry.server.tsxnow defaults HTML documents toCache-Control: no-store(loaders can override). Source-level tests inserver/server.test.ts+entry.server.test.ts. - 2026-05-17 —
03-scaling/asset-cdn: add cache-purge helper scriptscripts/cdn/bunny-purge.tswraps 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.ymlnow runs the purge after the Sentry release marker; the step inline-skips whenBUNNY_API_KEYis unset. - 2026-05-17 —
03-scaling/asset-cdn: document cdn setup and provider alternativesAuthoreddocs/ops/asset-cdn.mdcovering 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 exampleAddedASSET_CDN_URL,BUNNY_PULL_ZONE_ID,BUNNY_API_KEYtopackages/config/src/catalog.tsand.env.example. Env-drift contract passes. - Outstanding (operator-owned):
- Provision Bunny.net pull zones (staging + production) per the
runbook in
docs/ops/asset-cdn.md. - Add
BUNNY_PULL_ZONE_ID+BUNNY_API_KEYas Gitea secrets and Coolify env vars. - Set
ASSET_CDN_URLin Coolify forstaging+productiondeploy targets. - Run the smoke tests in the runbook against staging.
- 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.
- Provision Bunny.net pull zones (staging + production) per the
runbook in
Lessons Learned
(Optional am Task-Ende.)