zhongwei/gh-jezweb-claude-skills-skills-sveltia-cms
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:25:30 +08:00
commit cc481ebf7e
18 changed files with 3271 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

347
templates/cloudflare-workers/setup-guide.md Normal file
View File

@@ -0,0 +1,347 @@
# 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)
```bash
# 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:
```bash
mkdir -p workers/sveltia-auth
cp templates/cloudflare-workers/* workers/sveltia-auth/
```
2. Update `wrangler.jsonc` with your account ID
3. Deploy:
```bash
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:
```bash
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:
```bash
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:
```yaml
# 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**:
```yaml
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:**
```bash
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:**
```bash
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
```bash
npx wrangler secret put GITLAB_APPLICATION_ID
# Paste Application ID
npx wrangler secret put GITLAB_SECRET
# Paste Secret
```
### 3. Update CMS Config
```yaml
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:**
```yaml
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
- **Official Auth Worker**: https://github.com/sveltia/sveltia-cms-auth
- **Sveltia CMS Docs**: https://github.com/sveltia/sveltia-cms
- **Wrangler Docs**: https://developers.cloudflare.com/workers/wrangler/
- **OAuth 2.0 Spec**: https://oauth.net/2/
---
**Last Updated**: 2025-10-24