Skip to main content

Cloudflare Setup Guide (Pages + Access)

This guide walks you through publishing the TVL docs site to Cloudflare Pages and optionally protecting it with Cloudflare Access (Google SSO). Follow ADR-0052.

Prerequisites​

  • Cloudflare account with access to the target zone (thevillalife.com)
  • GitHub admin access to add repository secrets
  • Node.js 20+ and pnpm 8.x locally (optional, for local testing)

1) Create Cloudflare API Token (for GitHub Actions)​

  1. Open https://dash.cloudflare.com/profile/api-tokens
  2. Create Token → Use template: "Edit Cloudflare Workers" (or custom)
  3. Permissions (minimum):
    • Account → Cloudflare Pages → Edit
  4. Copy the generated token

2) Add GitHub Repository Secrets​

Add these secrets at Settings → Secrets and variables → Actions:

  • CLOUDFLARE_API_TOKEN: value from step 1
  • CLOUDFLARE_ACCOUNT_ID: your Cloudflare account ID (Dashboard → Workers & Pages → right sidebar)

The workflow at .github/workflows/docs.yml uses these to deploy.

3) Create Cloudflare Pages Project (one-time)​

  1. Go to Cloudflare Dashboard → Workers & Pages → Create application → Pages
  2. Connect to Git and select repository the-villa-life/tvl-platform
  3. Configure build:
    • Project name: tvl-docs
    • Production branch: main
    • Build command: 
      cd apps/docs-site && pnpm install --frozen-lockfile && pnpm docusaurus gen-api-docs all && pnpm build
    • Build output directory: apps/docs-site/build
    • Root directory: leave empty
  4. Environment variables:
    • NODE_VERSION = 20
  5. Save and Deploy. First build takes ~3–5 minutes.

Notes:

  • Our CI workflow also deploys on push to main. Keeping both enabled is fine; Cloudflare will use the latest successful deployment.

4) Custom Domain (optional)​

If you want https://docs.thevillalife.com:

  1. Pages → tvl-docs → Custom domains → Set up a custom domain
  2. Enter docs.thevillalife.com
  3. DNS:
    • If DNS hosted in Cloudflare: auto-configured
    • Else, add CNAME:
      • Name: docs
      • Target: tvl-docs.pages.dev
      • Proxy: Enabled (orange cloud)
  4. Wait 5–10 minutes for SSL provisioning, then verify HTTPS.

5) Cloudflare Access (optional, free up to 50 users)​

Protect the docs with Google SSO:

  1. Enable Zero Trust: Dashboard → Zero Trust (free plan)
  2. Add Identity Provider: Zero Trust → Settings → Authentication → Add new → Google
  3. Create Google OAuth Client:
    • https://console.cloud.google.com/apis/credentials
    • OAuth 2.0 Client ID → Web application
    • Redirect URI: 
      https://<your-team>.cloudflareaccess.com/cdn-cgi/access/callback
  4. Paste Client ID/Secret into Cloudflare and save
  5. Create Access Application: Zero Trust → Access → Applications → Add → Self-hosted
    • Name: TVL Documentation
    • Domain: docs.thevillalife.com
    • Session duration: 24h (suggested)
  6. Policy: Allow → Include emails or Google Workspace group (e.g., @thevillalife.com)
  7. Test: Visit https://docs.thevillalife.com → Google login → access granted

6) Verify CI/CD​

  • On push to main affecting docs/** or apps/docs-site/**, GitHub Actions runs .github/workflows/docs.yml and deploys to Cloudflare Pages (tvl-docs).
  • Preview deployments appear on PRs via Cloudflare.

Local Testing (optional)​

cd apps/docs-site
pnpm install
pnpm docusaurus gen-api-docs all
pnpm build && pnpm serve --port 3001
# http://localhost:3001

Troubleshooting​

  • Build tool not found (pnpm): ensure NODE_VERSION=20 in Pages settings
  • OpenAPI generation fails: validate docs/reference/api/openapi.yaml 
    npx @apidevtools/swagger-cli validate docs/reference/api/openapi.yaml
  • 404 after deploy: verify output dir apps/docs-site/build and baseUrl: '/' in apps/docs-site/docusaurus.config.ts
  • SSL pending: confirm CNAME docs → tvl-docs.pages.dev and wait 10–15 minutes
  • Preview deployments missing: authorize Cloudflare Pages GitHub App for PR permissions

References​

  • ADR-0052: docs/reference/decisions/adr-0052-docusaurus-cloudflare-pages.md
  • CI: .github/workflows/docs.yml
  • Docusaurus config: apps/docs-site/docusaurus.config.ts
  • Deployment guide: apps/docs-site/DEPLOYMENT.md
  • Cloudflare Pages docs: https://developers.cloudflare.com/pages/
  • Cloudflare Access docs: https://developers.cloudflare.com/cloudflare-one/applications/