Wrangling the wrangler

docs/cloudflare-worker.md

@@ -0,0 +1,112 @@
+# Cloudflare Worker Static Assets
+
+This project uses Astro static output, so Cloudflare only needs the generated `dist/` directory.
+
+The public site is deployed as a Cloudflare Worker serving static assets. Wrangler supports deploying a directory of static assets with `wrangler deploy dist`.
+
+## URL Sets
+
+Keep three sets of URLs separate:
+
+- Local development: `.env`, used by Docker Compose and `astro dev`.
+- Test Worker deployment: `.env.worker.test`, used by `npm run build:worker:test` and `npm run deploy:worker:test`.
+- Production Worker deployment: `.env.worker.prod`, used by `npm run build:worker:prod` and `npm run deploy:worker:prod`.
+
+The important distinction is that Astro fetches Directus content during the build. The URLs in the env file selected for the build are baked into the generated static files.
+
+## First-Time Setup
+
+Copy the example files and fill in the real values:
+
+```bash
+cp .env.worker.test.example .env.worker.test
+cp .env.worker.prod.example .env.worker.prod
+```
+
+Do not commit `.env.worker.test` or `.env.worker.prod`; they contain API tokens.
+
+Create a Cloudflare API token that can deploy Workers, then set these values in both env files:
+
+```env
+CLOUDFLARE_ACCOUNT_ID=...
+CLOUDFLARE_API_TOKEN=...
+```
+
+In practice, Wrangler's static asset upload currently works reliably with a user-owned API token scoped to the target account. Account-owned tokens may authenticate successfully with `wrangler whoami` but still fail during `workers/scripts/<name>/assets-upload-session` with `Authentication error [code: 10000]`.
+
+For a user-owned token, start with these permissions:
+
+```text
+Account -> Workers Scripts -> Edit
+Account -> Account Settings -> Read
+User -> Memberships -> Read
+```
+
+If the deploy command manages Worker routes or domains, also grant the matching zone/worker route permissions for the target domain.
+
+Each env file also names the target Worker:
+
+```env
+CF_WORKER_NAME=swansea-airfield-test
+```
+
+For Directus, use public HTTPS URLs in Worker env files. Do not use Docker-only hostnames such as `http://directus:8055` outside Docker Compose.
+
+## Build Locally For Test
+
+When working through Docker Compose:
+
+```bash
+docker compose exec web npm run build:worker:test
+```
+
+This loads `.env.worker.test`, fetches content from the test Directus URL, and writes static files to `dist/`.
+
+## Deploy To The Test Worker
+
+```bash
+docker compose exec web npm run deploy:worker:test
+```
+
+This builds with `.env.worker.test`, then uploads `dist/` to the Worker named by `CF_WORKER_NAME`.
+
+## Deploy To The Production Worker
+
+```bash
+docker compose exec web npm run deploy:worker:prod
+```
+
+This builds with `.env.worker.prod`, then uploads `dist/` to the production Worker.
+
+## Routes And Domains
+
+The deploy wrapper can optionally attach a route or custom domain if the env file sets one of these:
+
+```env
+CF_WORKER_ROUTE=swansea-airport.wales/*
+CF_WORKER_DOMAIN=swansea-airport.wales
+```
+
+Leave both unset if routes/domains are managed in the Cloudflare dashboard.
+
+## Gitea CI Shape
+
+In Gitea Actions, create the selected env file from CI secrets, then run:
+
+```bash
+npm ci
+npm run deploy:worker:prod
+```
+
+The deploy script treats the selected env file as the source of truth. This is deliberate because the Docker Compose `web` service already has local development variables in its environment, and production/test deploys need to override them.
+
+## Content Updates
+
+Static deploys are snapshots. If Directus content changes after deployment, the Worker will not update until another build and deploy runs.
+
+For production, trigger `npm run deploy:worker:prod` from either:
+
+- a code push to Gitea,
+- a manual Gitea Actions workflow,
+- a Directus webhook that calls your CI runner,
+- or a scheduled CI job.