Create cloudflare-cache-strategy.md via n8n

PBS/Tech/Projects/cloudflare-cache-strategy.md

@@ -0,0 +1,107 @@
+---
+project: cloudflare-cache-strategy
+type: project-plan
+status: active
+tags:
+  - pbs
+  - cloudflare
+  - caching
+  - n8n
+  - automation
+  - production
+created: 2026-03-30
+updated: 2026-03-30
+path: PBS/Tech/Projects/
+---
+
+# Cloudflare Cache Strategy - Cookie Bypass + Auto-Purge
+
+## Problem
+
+After the production server migration (clone → update → promote),
+Cloudflare caching broke backend tools (n8n, Gitea) and WordPress admin
+functionality. The existing IP-based cache bypass rule failed — Jenny saved
+post edits that reverted on reload due to stale cached pages being served.
+
+The IP-based approach is inherently fragile: ISP IP changes, rule ordering
+conflicts with new exception rules, and doesn't scale.
+
+## Decision
+
+Replace IP-based bypass with a **hybrid approach**: custom cookie bypass
+for admin users + n8n-driven auto-purge on content publish/update.
+
+## Plan
+
+### Phase 1: Cookie Bypass
+
+- [ ] Define custom cookie name (`pbs_admin_bypass`) and generate a random
+secret value
+- [ ] Test manually: set cookie in browser DevTools, verify Cloudflare
+serves `CF-Cache-Status: BYPASS`
+- [ ] Add WPCode Lite PHP snippet that sets the cookie automatically on
+admin-role login
+- [ ] Replace Cloudflare "Bypass Cache - Admin IPs" rule with new rule:
+  - **Rule name:** Bypass Cache - PBS Admins
+  - **Match:** Cookie contains `pbs_admin_bypass`
+  - **Action:** Bypass cache
+- [ ] Ensure rule is ordered above "Cache Everything" rule
+- [ ] Delete old IP-based bypass rule
+- [ ] Verify Jenny's workflow: edit post → save → reload → changes persist
+
+### Phase 2: Cloudflare API Token
+
+- [ ] Create scoped Cloudflare API token with only `Zone.Cache Purge`
+permission
+- [ ] Store token securely (n8n credentials store)
+- [ ] Note Zone ID for API calls
+
+### Phase 3: n8n Auto-Purge Workflow
+
+- [ ] Configure WordPress webhook(s) to fire on:
+  - Post publish/update
+  - Page publish/update
+  - WooCommerce product update
+  - WPRM recipe update
+- [ ] Build n8n workflow:
+  - Webhook node receives WordPress payload (includes post/page URL)
+  - HTTP Request node calls Cloudflare purge API for the specific URL
+  - (Optional) Also purge homepage URL — decision pending
+- [ ] Test: publish a post → verify cached version updates within seconds
+- [ ] Add Google Chat notification on purge (optional)
+
+## Current Cloudflare Cache Rules (Target State)
+
+1. Bypass Cache - WP Admin Paths (`/wp-admin`, `/wp-login.php`)
+2. Bypass Cache - PBS Admins (cookie: `pbs_admin_bypass`)
+3. Bypass Cache - n8n/Gitea (existing exception rules)
+4. Cache Everything (2hr Edge TTL, 1 day Browser TTL, serve stale while
+revalidating)
+
+## Key Technical Notes
+
+- Cloudflare purge API endpoint: `POST
+/client/v4/zones/{ZONE_ID}/purge_cache`
+- Targeted purge supports up to 30 URLs per call
+- n8n and Gitea subdomains have Cloudflare proxy disabled (separate fix)
+- Cookie approach avoids Ultimate Member conflict — site members won't have
+the custom cookie
+- If Ultimate Member membership activates later, this approach still works
+(unlike `wordpress_logged_in` cookie)
+
+## Open Questions
+
+- [ ] Whether to auto-purge homepage on every content update
+- [ ] Whether to add a private URL endpoint as a fallback cookie-setting
+method
+
+## Cloudflare API Purge Example
+
+```bash
+curl -X POST "
+https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/purge_cache" \
+  -H "Authorization: Bearer YOUR_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{"files":["https://plantbasedsoutherner.com/updated-post-slug/"]}'
+```
+...sent from Jenny & Travis