Skip to main content

Cloudflare Setup Guide

Complete guide for setting up Cloudflare services for the freeAIhashtags.com monorepo.

Overview​

freeAIhashtags.com uses the following Cloudflare services:

  • Cloudflare Workers: Frontend hosting (apps/web via OpenNext)
  • Cloudflare Workers: API Gateway (apps/api)
  • Cloudflare KV: API caching and rate limiting
  • Cloudflare Turnstile: CAPTCHA alternative

1. Create a Cloudflare Account​

  1. Go to https://dash.cloudflare.com/sign-up
  2. Enter your email and create a password
  3. Click Sign Up
  4. Verify your email address if requested

2. Create Pages Project for Frontend​

  1. Log in to the Cloudflare Dashboard
  2. In the sidebar, click Workers & Pages
  3. Click Create application
  4. Select the Pages tab
  5. Click Create using Direct Upload
    • Why? We have GitHub Actions workflows that give us more control
    • Do not select "Connect to Git"
  6. Project Name: Enter faiht-frontend
  7. Click Create Project

[!NOTE] Both main and sandbox branches deploy to the same project.

  • Production (main): Uses production environment variables
  • Sandbox (sandbox): Uses sandbox environment variables

3. Generate API Token​

You need an API token to allow GitHub Actions to deploy to Cloudflare.

  1. Go to User Profile > API Tokens
  2. Click Create Token
  3. Use the Edit Cloudflare Workers template or Create Custom Token
  4. Permissions:
    • Account > Cloudflare Pages > Edit
    • Account > Workers Scripts > Edit
    • Account > Workers KV Storage > Edit
  5. Account Resources: Include All accounts (or select your specific account)
  6. Click Continue to summary → Create Token
  7. COPY THIS TOKEN IMMEDIATELY (you won't see it again)

4. Get Your Account ID​

  1. Go to your Cloudflare Dashboard
  2. The URL will look like: https://dash.cloudflare.com/<ACCOUNT_ID>/...
  3. Copy the <ACCOUNT_ID> string from the URL

Alternative: Click on your account name in the top right and look for "Account ID"

5. Configure Cloudflare Turnstile​

Turnstile is Cloudflare's CAPTCHA alternative (free and unlimited).

  1. Go to the Cloudflare Dashboard
  2. In the sidebar, click Turnstile
  3. Click Add Widget (or Add Site)
  4. Widget Name: faiht-frontend
  5. Domain:
    • Add your production domain: freeaihashtags.com
    • Add sandbox domain: faiht-frontend.adeel-zain-work.workers.dev
    • Add localhost for local testing
  6. Widget Mode: Select Managed (Recommended)
  7. Click Create
  8. Copy Keys:
    • Site Key: Public (can be embedded in frontend)
    • Secret Key: Private (for server-side verification)

6. Setup KV Namespaces​

KV namespaces are required for the API Gateway's caching and rate limiting.

See: KV Namespace Setup for detailed instructions.

Quick summary:

cd apps/api

# Create sandbox namespace
wrangler kv:namespace create "FAIHT_CACHE" --env sandbox

# Create production namespace
wrangler kv:namespace create "FAIHT_CACHE"

# Add IDs to GitHub Secrets

7. Configure GitHub Secrets & Variables​

Variables (Non-Sensitive)​

Go to: Repository → Settings → Secrets and variables → Actions → Variables

Click New repository variable for each:

Variable NameValue
CLOUDFLARE_ACCOUNT_ID<your-account-id> (from Step 4)

Secrets (Sensitive)​

Go to: Repository → Settings → Secrets and variables → Actions → Secrets

Click New repository secret for each:

Secret NameValueSource
CLOUDFLARE_API_TOKEN<your-api-token>Step 3
SANDBOX_KV_NAMESPACE_ID<namespace-id>Step 6
PROD_KV_NAMESPACE_ID<namespace-id>Step 6

For Turnstile (per environment):

  • SANDBOX_NEXT_PUBLIC_TURNSTILE_SITE_KEY
  • SANDBOX_TURNSTILE_SECRET_KEY
  • PROD_NEXT_PUBLIC_TURNSTILE_SITE_KEY
  • PROD_TURNSTILE_SECRET_KEY

8. Update Supabase CORS​

Add your Cloudflare Pages URLs to Supabase CORS configuration:

  1. Go to Supabase Dashboard
  2. Navigate to Settings > Edge Functions
  3. Add or update ACCESS_CONTROL_ALLOW_ORIGIN: 
    http://localhost:3000,https://freeaihashtags.com,https://faiht-frontend.adeel-zain-work.workers.dev

[!IMPORTANT] Whenever you deploy to a new URL (like a preview deployment), add it to the CORS list.

9. Verify Setup​

Test Pages Deployment​

cd apps/web
pnpm build
npx wrangler pages deploy out --project-name=faiht-frontend --branch=sandbox

Test Worker Deployment​

cd apps/api
npx wrangler deploy

Test KV Access​

cd apps/api
wrangler kv:key put --binding=FAIHT_CACHE "test-key" "test-value" --env sandbox
wrangler kv:key get --binding=FAIHT_CACHE "test-key" --env sandbox

Next Steps​