Cloudflare Pages Deployment with Google OAuth

This guide covers deploying the VitePress documentation site to Cloudflare Pages with Google OAuth authentication via Cloudflare Access.

NB: This is a work in progress and not yet complete, but the idea is cool.

Overview

• Local Development: No authentication (Docker only)
• Production: Cloudflare Pages with Cloudflare Access (Google OAuth)
• Access Control: Developer emails + founder admin domain
• Deployment: Automated via GitHub Actions

Prerequisites

1. Cloudflare account
2. Domain configured in Cloudflare
3. Google Cloud project for OAuth credentials
4. GitHub repository secrets configured

Step 1: Create Cloudflare Pages Project

Via Cloudflare Dashboard

1. Go to Cloudflare Dashboard → Pages
2. Click Create a project
3. Select Direct Upload (we'll use GitHub Actions, not Git integration)
4. Project name: wedissimo-docs
5. Click Create project

Get Required Credentials

You'll need these for GitHub Actions:

1. Cloudflare Account ID:

   • Dashboard → Pages → Account ID (in URL or sidebar)
   • Format: 1234567890abcdef1234567890abcdef

2. Cloudflare API Token:

   • Dashboard → My Profile → API Tokens → Create Token
   • Use template: Edit Cloudflare Workers
   • Or create custom token with permissions:
     • Account → Cloudflare Pages → Edit
   • Copy the token (shown only once)

Step 2: Configure GitHub Secrets

Add these secrets to your GitHub repository:

Settings → Secrets and variables → Actions → New repository secret

Secret Name	Value	Where to Find
CLOUDFLARE_API_TOKEN	Your API token	From Step 1
CLOUDFLARE_ACCOUNT_ID	Your account ID	From Step 1

Step 3: Set Up Google OAuth

Create OAuth Credentials

1. Go to Google Cloud Console

2. Select your project (or create new one)

3. Navigate to APIs & Services → Credentials

4. Click Create Credentials → OAuth 2.0 Client ID

5. Application type: Web application

6. Name: Wedissimo Docs - Cloudflare Access

7. Authorized redirect URIs:

   https://<your-team-name>.cloudflareaccess.com/cdn-cgi/access/callback

   Replace <your-team-name> with your Cloudflare team name (found in Zero Trust dashboard)

8. Click Create

9. Copy Client ID and Client Secret

Find Your Cloudflare Team Name

1. Go to Cloudflare Zero Trust Dashboard
2. Your team name is in the URL: https://<team-name>.cloudflareaccess.com
3. Or check: Settings → General → Team domain

Step 4: Configure Cloudflare Access

Enable Cloudflare Access

1. Go to Cloudflare Dashboard → Zero Trust
2. Navigate to Access → Applications
3. Click Add an application
4. Select Self-hosted

Application Configuration

Application Details:

• Application name: Wedissimo Developer Docs
• Session Duration: 24 hours (or your preference)
• Application domain:
  • Subdomain: docs (or your choice)
  • Domain: wedissimo.com (or your domain)
  • Path: Leave empty (protect entire site)

Identity Providers:

1. Click Add under Login Methods
2. Select Google
3. Enter your OAuth credentials:
   • Client ID: (from Step 3)
   • Client Secret: (from Step 3)
4. Click Save

Access Policies

Create policies to allow access:

Policy 1: Developer Emails

• Policy name: Developer Access
• Action: Allow
• Rule type: Include
• Selector: Emails
• Value: Add individual developer emails:

  developer1@example.com
  developer2@example.com

Policy 2: Founder Admin Domain

• Policy name: Founder Admin Domain
• Action: Allow
• Rule type: Include
• Selector: Emails ending in
• Value: @founderandlightning.com (or your admin domain)

Example Combined Policy:

Include:
  - Emails: dev1@example.com, dev2@example.com
  - Emails ending in: @founderandlightning.com

Click Save application

Step 5: Deploy via GitHub Actions

The deployment workflow is already configured in .github/workflows/deploy-docs.yml.

Trigger Deployment

Automatic:

• Push to main or staging branch
• Changes in docs/** directory

Manual:

• Go to Actions tab in GitHub
• Select Deploy VitePress Docs to Cloudflare Pages
• Click Run workflow

Workflow Overview

on:
  push:
    branches: [main, staging]
    paths: ['docs/**']
  workflow_dispatch:

jobs:
  deploy:
    - Checkout code
    - Setup Node.js 20
    - Install dependencies (docs/package.json)
    - Build VitePress (npm run build)
    - Deploy to Cloudflare Pages

Step 6: Configure Custom Domain (Optional)

Add Custom Domain to Cloudflare Pages

1. Cloudflare Dashboard → Pages → wedissimo-docs
2. Go to Custom domains tab
3. Click Set up a custom domain
4. Enter: docs.wedissimo.com
5. Cloudflare will automatically configure DNS

Update Cloudflare Access Application

1. Go back to Zero Trust → Access → Applications
2. Edit Wedissimo Developer Docs
3. Update Application domain to match custom domain
4. Save changes

Step 7: Verify Setup

Test Authentication Flow

1. Visit your docs URL: https://docs.wedissimo.com
2. You should see Cloudflare Access login page
3. Click Sign in with Google
4. Authenticate with allowed email
5. You should be redirected to docs site

Test Access Control

Allowed users:

• ✅ Individual developer emails (from Policy 1)
• ✅ Any email ending in @founderandlightning.com (from Policy 2)

Blocked users:

• ❌ Any other email addresses

Local Development (No Auth)

Local development runs without authentication:

# Start docs server (no auth required)
docker compose up wedissimo-docs

# Access at http://localhost:5174

The Docker container runs VitePress directly without any authentication layer.

Troubleshooting

"Access Denied" for Valid Users

Check:

1. Email is in allowed list or matches domain rule
2. Google OAuth consent screen is configured
3. User's email is verified in Google account

Redirect URI Mismatch

Error: redirect_uri_mismatch

Fix:

1. Check Google OAuth credentials
2. Ensure redirect URI matches exactly:

   https://<team-name>.cloudflareaccess.com/cdn-cgi/access/callback

3. No trailing slashes or extra characters

Deployment Fails

Check:

1. GitHub secrets are set correctly
2. Cloudflare API token has correct permissions
3. Build succeeds locally: cd docs && npm run build

Session Expires Too Quickly

Fix:

1. Go to Access application settings
2. Increase Session Duration (e.g., 24 hours, 7 days)
3. Save changes

Security Best Practices

Rotate Credentials Regularly

• Rotate Cloudflare API tokens every 90 days
• Rotate Google OAuth credentials annually
• Review access logs monthly

Monitor Access Logs

1. Zero Trust → Logs → Access
2. Review authentication attempts
3. Set up alerts for suspicious activity

Principle of Least Privilege

• Only grant access to users who need it
• Use domain-based rules for teams
• Individual emails for contractors/external developers

Cost Considerations

Cloudflare Pages:

• Free tier: 500 builds/month, unlimited requests
• Paid tier: $20/month for more builds

Cloudflare Access:

• Free tier: Up to 50 users
• Paid tier: $3/user/month for 50+ users

Recommendation: Start with free tier, upgrade if needed.

Maintenance

Adding New Developers

Option 1: Individual Email

1. Zero Trust → Access → Applications
2. Edit Wedissimo Developer Docs
3. Edit policy → Add email to list

Option 2: Use Domain

• If developer has @founderandlightning.com email, they're automatically allowed

Removing Access

1. Edit access policy
2. Remove email from list
3. User's session will expire based on session duration
4. Force immediate logout: Revoke user session in Access logs

Next Steps

• [ ] Set up Cloudflare Pages project
• [ ] Configure Google OAuth credentials
• [ ] Add GitHub secrets
• [ ] Configure Cloudflare Access policies
• [ ] Test deployment workflow
• [ ] Verify authentication works
• [ ] Add team members to access list

Related Documentation

• Cloudflare Pages Documentation
• Cloudflare Access Documentation
• VitePress Deployment Guide