zhongwei/gh-jezweb-claude-skills-skills-sveltia-cms
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cc481ebf7e97377e2900fba70fe869c62d01a2ee
gh-jezweb-claude-skills-ski…/templates/cloudflare-workers/setup-guide.md
Zhongwei Li cc481ebf7e Initial commit
2025-11-30 08:25:30 +08:00

7.8 KiB
Raw Blame History

Cloudflare Workers OAuth Proxy Setup

Complete guide to deploying Sveltia CMS authentication using Cloudflare Workers.

Overview

This OAuth proxy enables Sveltia CMS to authenticate with GitHub or GitLab without requiring a backend server. The Worker handles the OAuth flow securely.

Official Repository: https://github.com/sveltia/sveltia-cms-auth

Prerequisites

  • Cloudflare account (free tier works)
  • GitHub or GitLab account
  • Wrangler CLI installed (npm install -g wrangler)
  • Git repository with Sveltia CMS

Step 1: Deploy the Worker

Option A: Use Official Repository (Recommended)

# Clone the official auth worker
git clone https://github.com/sveltia/sveltia-cms-auth
cd sveltia-cms-auth

# Install dependencies
npm install

# Login to Cloudflare (if not already logged in)
npx wrangler login

# Deploy to Workers
npx wrangler deploy

Output:

 ⛅️ wrangler 3.x.x
-------------------
Uploaded sveltia-cms-auth (x.x KiB)
Published sveltia-cms-auth (x.xx sec)
  https://sveltia-cms-auth.<your-subdomain>.workers.dev

Save this URL - you'll need it later!

Option B: One-Click Deploy

  1. Visit https://github.com/sveltia/sveltia-cms-auth
  2. Click the "Deploy to Cloudflare Workers" button
  3. Follow the deployment wizard
  4. Note the deployed Worker URL

Option C: Use This Template

If you want to customize the Worker:

  1. Copy template to your project:

    mkdir -p workers/sveltia-auth
cp templates/cloudflare-workers/* workers/sveltia-auth/

  2. Update wrangler.jsonc with your account ID

  3. Deploy:

    cd workers/sveltia-auth
npx wrangler deploy

Step 2: Register OAuth App on GitHub

  1. Go to GitHub Settings: https://github.com/settings/developers

  2. Click "New OAuth App"

  3. Fill in details:

    • Application name: Your Site CMS (or any name)
    • Homepage URL: https://yourdomain.com (your actual site)
    • Authorization callback URL: https://sveltia-cms-auth.<your-subdomain>.workers.dev/callback
      • ⚠️ Critical: This must be the Worker URL + /callback
      • ❌ NOT: https://yourdomain.com/callback
      • ✅ Example: https://sveltia-cms-auth.my-account.workers.dev/callback

  4. Click "Register application"

  5. Save these values:

    • Client ID: Ov23li... (visible immediately)
    • Client Secret: Click "Generate a new client secret" and copy it (shown once!)

Step 3: Configure Worker Environment Variables

Set the secrets using Wrangler CLI:

cd sveltia-cms-auth  # or your Worker directory

# Set GitHub Client ID
npx wrangler secret put GITHUB_CLIENT_ID
# Paste your Client ID when prompted

# Set GitHub Client Secret
npx wrangler secret put GITHUB_CLIENT_SECRET
# Paste your Client Secret when prompted

Optional: Restrict to specific domains:

npx wrangler secret put ALLOWED_DOMAINS
# Enter domains when prompted, e.g.: yourdomain.com,*.yourdomain.com

Wildcards:

  • yourdomain.com - Exact match only
  • *.yourdomain.com - All subdomains (www.yourdomain.com, blog.yourdomain.com)
  • yourdomain.com,*.yourdomain.com - Both root and subdomains

Step 4: Update Sveltia CMS Config

Add the base_url to your CMS configuration:

# static/admin/config.yml (Hugo)
# or admin/config.yml (Jekyll/11ty)
# or public/admin/config.yml (Astro/Next.js)

backend:
  name: github
  repo: owner/repo  # Your GitHub repository
  branch: main      # Your default branch
  base_url: https://sveltia-cms-auth.<your-subdomain>.workers.dev  # ← Add this line

Example:

backend:
  name: github
  repo: jezweb/my-blog
  branch: main
  base_url: https://sveltia-cms-auth.my-account.workers.dev

Step 5: Test Authentication

  1. Start your local dev server:

    hugo server  # or jekyll serve, or npm run dev

  2. Open admin in browser:

    http://localhost:1313/admin/  # Hugo
http://localhost:4000/admin/  # Jekyll
http://localhost:8080/admin/  # 11ty
http://localhost:4321/admin/  # Astro

  3. Click "Login with GitHub"

  4. Authorize the app when GitHub asks

  5. You should be redirected back to the CMS with content loaded

Step 6: Deploy Your Site

  1. Commit changes:

    git add static/admin/config.yml  # or your admin path
git commit -m "Add Cloudflare Workers OAuth for Sveltia CMS"
git push

  2. Deploy to your hosting:

    • Cloudflare Pages: Automatic on push
    • Vercel: Automatic on push
    • Netlify: Automatic on push
    • GitHub Pages: GitHub Actions workflow

  3. Test on production:

    https://yourdomain.com/admin/

GitLab Setup (Alternative)

If using GitLab instead of GitHub:

1. Create GitLab Application

  1. Go to https://gitlab.com/-/profile/applications
  2. Click "Add new application"
  3. Fill in:
    • Name: Your Site CMS
    • Redirect URI: https://sveltia-cms-auth.<your-subdomain>.workers.dev/callback
    • Scopes: Check api and write_repository
  4. Click "Save application"
  5. Copy Application ID and Secret

2. Set Worker Secrets

npx wrangler secret put GITLAB_APPLICATION_ID
# Paste Application ID

npx wrangler secret put GITLAB_SECRET
# Paste Secret

3. Update CMS Config

backend:
  name: gitlab
  repo: group/project
  branch: main
  base_url: https://sveltia-cms-auth.<your-subdomain>.workers.dev

Troubleshooting

Authentication Fails

Problem: "Error: Failed to authenticate"

Solutions:

  1. Check callback URL matches exactly (Worker URL + /callback)
  2. Verify secrets are set: npx wrangler secret list
  3. Test Worker directly: curl https://your-worker.workers.dev/health
  4. Check browser console for CORS errors

Redirect to Wrong Domain

Problem: Redirects to api.netlify.com/auth

Solutions:

  1. Ensure base_url is in config.yml
  2. Hard refresh browser (Ctrl+Shift+R)
  3. Clear browser cache

CORS Errors

Problem: "Cross-Origin-Opener-Policy blocked"

Solutions:

  1. Add COOP header to site (see SKILL.md Error #8)
  2. Set Cross-Origin-Opener-Policy: same-origin-allow-popups
  3. For Cloudflare Pages, add _headers file: 
    /*
  Cross-Origin-Opener-Policy: same-origin-allow-popups

Worker Not Found (404)

Problem: Worker URL returns 404

Solutions:

  1. Verify deployment: npx wrangler deployments list
  2. Check Worker name in wrangler.jsonc
  3. Wait 1-2 minutes after deployment (DNS propagation)

Security Best Practices

  1. Never commit secrets - Use npx wrangler secret put
  2. Restrict domains - Set ALLOWED_DOMAINS for production
  3. Use HTTPS only - Sveltia CMS requires secure context
  4. Rotate secrets periodically - Update GitHub OAuth secrets every 6-12 months
  5. Monitor access logs - Check Cloudflare Workers dashboard for unusual activity

Custom Domain (Optional)

To use a custom domain for your OAuth Worker:

  1. Add Worker route in Cloudflare:

    • Dashboard > Workers > Your Worker > Triggers
    • Add custom domain: auth.yourdomain.com

  2. Update GitHub OAuth callback:

    • Change to: https://auth.yourdomain.com/callback

  3. Update CMS config:

    backend:
  base_url: https://auth.yourdomain.com

Cost

Cloudflare Workers Free Tier:

  • 100,000 requests/day
  • 10ms CPU time per request
  • More than enough for CMS authentication

Typical usage: 50-100 requests/month for small teams

Additional Resources

Last Updated: 2025-10-24

Reference in New Issue View Git Blame Copy Permalink