egfh-website/docs/cloudflare-worker.md

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:

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:

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:

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:

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:

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

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

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:

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:

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.