From 80f4d9f19843f68149aaa525e35f9a1c2efdda12 Mon Sep 17 00:00:00 2001 From: zwitschi Date: Mon, 10 Aug 2026 12:44:46 +0200 Subject: [PATCH] docs: add cloudflare pages, cache rules docs and fix relative links --- docs/SETUP.md | 6 +- docs/architecture/README.md | 2 +- docs/architecture/adr/ADR-003-tech-stack.md | 2 +- .../infrastructure}/cloudflare/cache-rules.md | 0 docs/operations/cloudflare-pages-setup.md | 64 +++++++++++++++++++ docs/operations/gitea-cloudflare-pages.md | 5 ++ 6 files changed, 74 insertions(+), 5 deletions(-) rename {infrastructure => docs/infrastructure}/cloudflare/cache-rules.md (100%) create mode 100644 docs/operations/cloudflare-pages-setup.md diff --git a/docs/SETUP.md b/docs/SETUP.md index 805a693..ea1f8df 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -223,7 +223,7 @@ flowchart LR - Use Cloudflare proxied DNS with Full (strict) TLS so browser traffic uses `https://linearvoid.tv`, `wss://linearvoid.tv/ws`, and `https://media.linearvoid.tv`. 6. **Apply cache behavior**: - - Configure the `.m4s` and `.m3u8` cache rules from `infrastructure/cloudflare/cache-rules.md`. + - Configure the `.m4s` and `.m3u8` cache rules from [cache-rules](../docs/infrastructure/cloudflare/cache-rules.md). - Enable Smart Tiered Cache for the R2-backed hostname. - If you need header normalization for immutable segment caching, deploy `infrastructure/cloudflare/worker.js` to the same zone. @@ -272,7 +272,7 @@ Configure Cloudflare Cache Rules: 4. Validate behavior using response headers: - `Cf-Cache-Status` should move from `MISS` to `HIT` for hot objects -Reference: `infrastructure/cloudflare/cache-rules.md`. +Reference: [cache-rules](../docs/infrastructure/cloudflare/cache-rules.md). ### 4. Cloudflare Pages @@ -557,7 +557,7 @@ To allow the Gitea Actions runner (or your local machine) to deploy to the remot 1. **Provision VPS**: Use Hetzner Cloud CX22 in Ashburn, VA (per ADR-001). 2. **Configure Cloudflare**: - Create R2 bucket with `enam` location hint. - - Set up custom media domain (`media.linearvoid.tv`) with the cache rules from `infrastructure/cloudflare/cache-rules.md`. + - Set up custom media domain (`media.linearvoid.tv`) with the cache rules from [cache-rules](../docs/infrastructure/cloudflare/cache-rules.md). - Point `linearvoid.tv` and `www.linearvoid.tv` at the app entrypoint, then redirect `www` to the apex domain. - Use Full (strict) TLS for both app and media hostnames. - Apply the Worker from `infrastructure/cloudflare/worker.js` for advanced header management. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 6d1134e..1d4e160 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -669,7 +669,7 @@ Security is split between edge controls (Cloudflare), reverse proxy controls (ng #### Transport and Edge Protection - Public traffic uses HTTPS/WSS at the edge. -- Cloudflare WAF and rate limiting are part of the baseline (see `infrastructure/cloudflare/cache-rules.md`). +- Cloudflare WAF and rate limiting are part of the baseline (see [cache-rules](../docs/infrastructure/cloudflare/cache-rules.md)). - Cloudflare Worker can enforce immutable cache headers for segment paths (`infrastructure/cloudflare/worker.js`). #### Reverse Proxy Enforcement (nginx) diff --git a/docs/architecture/adr/ADR-003-tech-stack.md b/docs/architecture/adr/ADR-003-tech-stack.md index 64c1b05..c997cfb 100644 --- a/docs/architecture/adr/ADR-003-tech-stack.md +++ b/docs/architecture/adr/ADR-003-tech-stack.md @@ -38,7 +38,7 @@ We must explicitly document language/runtime choices per module and the assumpti 1. All video assets **must** be normalized before being added to any playlist (H.264, AAC, 30 fps constant, 2s keyframes, CRF encoding). 2. Deployment is **Docker-first**; services will be containerized. -3. Cloudflare is the primary CDN and will be configured with specific [Cache Rules](../../../infrastructure/cloudflare/cache-rules.md). +3. Cloudflare is the primary CDN and will be configured with specific [Cache Rules](../../infrastructure/cloudflare/cache-rules.md) for HLS segments and manifests. 4. Chat does **not** require end-to-end encryption in v1 (separate ADR if needed). 5. Single VPS origin initially; multi-region is a later evolution. 6. Monitoring focuses on playout health, cache hit ratio, and R2 operation counts. diff --git a/infrastructure/cloudflare/cache-rules.md b/docs/infrastructure/cloudflare/cache-rules.md similarity index 100% rename from infrastructure/cloudflare/cache-rules.md rename to docs/infrastructure/cloudflare/cache-rules.md diff --git a/docs/operations/cloudflare-pages-setup.md b/docs/operations/cloudflare-pages-setup.md new file mode 100644 index 0000000..262221a --- /dev/null +++ b/docs/operations/cloudflare-pages-setup.md @@ -0,0 +1,64 @@ +# Cloudflare Pages & Workers Setup — Linear Void + +Linear Void uses two Cloudflare products: + +| Product | Purpose | What | +| ----------- | ------------------ | ------------------------------------------------------------------------------------ | +| **Pages** | Static SPA hosting | Vite-built frontend (`frontend/dist`) deployed via Git integration or Direct Upload | +| **Workers** | Edge cache logic | `infrastructure/cloudflare/worker.js` — adds immutable cache headers to HLS segments | + +Both are managed under **Workers & Pages** in the Cloudflare dashboard. + +## Dashboard URLs + +| Resource | URL | +| ------------------------ | ---------------------------------------------------------------------------------------------- | +| Workers & Pages overview | `https://dash.cloudflare.com/{accountId}/workers-and-pages` | +| Worker: linearvoid | `https://dash.cloudflare.com/{accountId}/workers/services/view/linearvoid/production/settings` | +| Pages project | `https://dash.cloudflare.com/{accountId}/pages/view/linearvoid` | +| API tokens | | + +## 1) Worker: `linearvoid` (edge cache headers) + +The Worker at `infrastructure/cloudflare/worker.js` runs on the `linearvoid` Workers service. It intercepts requests and adds immutable `Cache-Control` headers to `.m4s` segment files. + +Deploy via Wrangler CLI: + +```bash +npx wrangler deploy infrastructure/cloudflare/worker.js +``` + +Or paste into the Workers dashboard at the URL above (Quick Edit). + +## 2) Pages: Static frontend + +Two approaches — pick one: + +### Option A: Git integration (recommended) + +Connect the Gitea repository directly in Cloudflare Pages: + +1. Pages → Create a project → Connect to Git +2. Link `git.allucanget.biz/zwitschi/linearvoid` +3. Build command: `cd frontend && npm run build` +4. Output directory: `frontend/dist` +5. Add custom domain: `linearvoid.tv` + +Cloudflare handles builds and deploys automatically on push. + +### Option B: Direct Upload via Gitea Actions + +Use `.gitea/workflows/pages-deploy.yml` to build in Gitea Actions and upload via the Cloudflare API. + +See [gitea-cloudflare-pages.md](./gitea-cloudflare-pages.md) for the workflow. + +## 3) Custom domains + +- `linearvoid.tv` → Pages project +- `www.linearvoid.tv` → redirect to `linearvoid.tv` +- `media.linearvoid.tv` → R2 bucket (separate; not Pages) + +## Related + +- [Gitea to Cloudflare Pages deployment guide](./gitea-cloudflare-pages.md) +- [Cloudflare & UptimeRobot checklist](./cloudflare-uptimerobot-checklist.md) diff --git a/docs/operations/gitea-cloudflare-pages.md b/docs/operations/gitea-cloudflare-pages.md index 023060d..c329da3 100644 --- a/docs/operations/gitea-cloudflare-pages.md +++ b/docs/operations/gitea-cloudflare-pages.md @@ -102,3 +102,8 @@ If the `cloudflare/pages-action@v1` action is unavailable from Gitea, use the di - Multi-page SPA (`vite.config.ts`) produces three entry points — Cloudflare Pages serves them correctly. - For SPA fallback routing, add a `frontend/public/_redirects` file with `/* /index.html 200` before building. - If deployments fail with 403, verify the API token has `Account → Cloudflare Pages → Edit` permission. + +## Related resources + +- Cloudflare Workers dashboard: `https://dash.cloudflare.com/{accountId}/workers/services/view/linearvoid/production/settings` — for managing the `infrastructure/cloudflare/worker.js` deployment +- Cloudflare Pages project: `https://dash.cloudflare.com/{accountId}/pages/view/linearvoid` — deployment history and custom domain settings