Skip to content
Cosmos Digital Services Docs

Deployment guide

Live behavior = Astro static output + gateway worker + image worker + Cloudflare Access and DNS configuration. Staging and production differ in wrangler.gateway.toml (worker names, routes, AUTH_WORKER_VERIFY_URL).

Section titled “Recommended deploy order”
  1. Auth worker (platform auth verify endpoint—ensure the URL configured in gateway matches what you deployed).
  2. Gateway worker (workers/wrangler.gateway.toml) — session, logout, protected paths, /api/* delegation.
  3. Astro build + static publish — yarn workspace cosmos-digital-services build (or build:staging for staging mode).
  4. Image worker (workers/wrangler.image.toml) — after or with static deploy; must match hostname routes.

From package.json, composite flows include worker:deploy (gateway + image) and deploy (runs npm run build then worker deploy—from monorepo root prefer yarn workspace cosmos-digital-services build then worker scripts for consistency with Yarn 4).

Staging vs production

Section titled “Staging vs production”
  • Use wrangler deploy --env staging / --env production (or your team’s equivalent) so the correct [env.*.vars] block applies.
  • Verify AUTH_WORKER_VERIFY_URL for the target environment matches the auth worker you intend (see workers/wrangler.gateway.toml).

Verification checklist

Section titled “Verification checklist”

After deploy:

  1. GET /api/auth/session returns JSON (not HTML) when the gateway route is active for that hostname.
  2. /portal (or another protected path) requires auth—unauthenticated users hit /login?redirect=....
  3. /portal/outgoing-mail reaches PUBLIC_OUTGOING_MAIL_WORKER_URL when authenticated; unauthenticated users are redirected to login.
  4. Header toggles between Login and Logout after Access completes and session returns success: true.
  5. Worker logs show auth verification traffic when exercising session and protected pages.
  6. Images with resize query params still hit the image worker routes (correct extension + width query per Worker flow).

Rollback triggers

Section titled “Rollback triggers”
  • Session endpoint returns HTML or 404 for /api/auth/session.
  • Mass redirect to login on public routes (check gateway routes and PROTECTED_PATH_PREFIXES).
  • CSP or CORS errors blocking session or mail after _headers change.
  • Image routes returning wrong content or 5xx after image worker or route change.

First actions: revert the last worker or _headers deploy, confirm Wrangler routes for the hostname, confirm AUTH_WORKER_VERIFY_URL for that environment.

Further reading

Section titled “Further reading”