Cloudflare Pages Deployment Guide#

This guide will help you deploy the atprotogo application to Cloudflare Pages.

Prerequisites#

1. Node.js 20+: Ensure you have Node.js version 20 or higher installed
2. Cloudflare Account: Sign up at https://dash.cloudflare.com
3. Cloudflare API Token: Create an API token at https://dash.cloudflare.com/profile/api-tokens with Pages and Workers permissions

Step 1: Set Up Environment#

Set your Cloudflare API token:

export CLOUDFLARE_API_TOKEN=your_api_token_here

Step 2: Create D1 Database#

Create the D1 database for your application:

npx wrangler d1 create atprotogo-db

This will output a database ID. Copy this ID and update wrangler.toml:

[[d1_databases]]
binding = "DB"
database_name = "atprotogo-db"
database_id = "YOUR_DATABASE_ID_HERE"  # Replace with actual ID

Step 3: Run Database Migrations#

Apply the database schema:

# For local development
npx wrangler d1 migrations apply atprotogo-db --local

# For production
npx wrangler d1 migrations apply atprotogo-db

Step 4: Create KV Namespaces#

Create KV namespaces for session and state storage:

npx wrangler kv:namespace create "SESSIONS_KV"
npx wrangler kv:namespace create "STATES_KV"

Each command will output a namespace ID. Update wrangler.toml:

[[kv_namespaces]]
binding = "SESSIONS_KV"
id = "YOUR_SESSIONS_KV_ID"  # Replace with actual ID

[[kv_namespaces]]
binding = "STATES_KV"
id = "YOUR_STATES_KV_ID"  # Replace with actual ID

Step 5: Set Environment Secrets#

Set up your secret environment variables:

SESSION_SECRET#

Generate a random secret:

openssl rand -base64 32

Then set it:

echo "YOUR_SECRET_HERE" | npx wrangler secret put SESSION_SECRET

PRIVATE_KEY_JWK#

Generate an EC key pair for OAuth:

# Generate using OpenSSL or your preferred method
# Then set it as a secret
echo '{"kty":"EC",...}' | npx wrangler secret put PRIVATE_KEY_JWK

Step 6: Update wrangler.toml#

Ensure your wrangler.toml has the production URL:

[vars]
PUBLIC_BASE_URL = "https://your-app-name.pages.dev"  # Update with your actual URL

Step 7: Set Up Local Development#

Create .dev.vars file for local development (already in .gitignore):

SESSION_SECRET=your-local-secret
PRIVATE_KEY_JWK={"kty":"EC",...}
PUBLIC_BASE_URL=http://localhost:8788

Step 8: Build and Deploy#

Option A: Direct Deployment with Wrangler#

Build the application:

npm run build

Deploy to Cloudflare Pages:

npx wrangler pages deploy .svelte-kit/cloudflare --project-name=atprotogo

Option B: GitHub Integration (Recommended)#

1. Push your code to GitHub
2. Go to Cloudflare Dashboard → Pages → "Create application"
3. Connect your GitHub repository
4. Configure build settings:
   • Build command: npm run build
   • Build output directory: .svelte-kit/cloudflare
   • Root directory: /
   • Node version: 20 or higher
5. Add environment variables in the dashboard:
   • SESSION_SECRET (secret)
   • PRIVATE_KEY_JWK (secret)
   • PUBLIC_BASE_URL (variable)
6. Bind D1 and KV resources in the "Settings" tab

Step 9: Test Local Development#

To test locally with Cloudflare's runtime:

npm run build
npx wrangler pages dev .svelte-kit/cloudflare \
  --compatibility-date=2024-01-01 \
  --d1=DB \
  --kv=SESSIONS_KV \
  --kv=STATES_KV

Verification Checklist#

After deployment, verify:

• Homepage loads without errors
• OAuth login/callback works
• Can create a new game
• Can join an existing game
• Moves are recorded correctly
• Image generation works (board images, OG images, reactions)
• Profile pages display correctly

Troubleshooting#

"D1 binding not available"#

• Verify wrangler.toml has correct database binding
• Check D1 database exists: npx wrangler d1 list
• Ensure migrations were applied

"KV binding not available"#

• Verify KV namespace IDs in wrangler.toml
• Check KV namespaces exist: npx wrangler kv:namespace list

OAuth errors#

• Verify PUBLIC_BASE_URL is set correctly
• Check SESSION_SECRET and PRIVATE_KEY_JWK are set
• Ensure OAuth callback URL matches the deployed URL

Image generation fails#

• Check that @cf-wasm/resvg is working correctly
• Verify static assets are accessible

Updating the Deployment#

When you make changes:

1. Code changes: Push to GitHub (if using GitHub integration) or run npx wrangler pages deploy
2. Database schema changes: Create a new migration file in migrations/ and run npx wrangler d1 migrations apply atprotogo-db
3. Environment variable changes: Update in Cloudflare dashboard or use wrangler secret put

Monitoring and Logs#

View logs in real-time:

npx wrangler pages deployment tail

Or view in Cloudflare Dashboard → Pages → Your Project → "Functions" tab.

Cost Estimates#

Cloudflare Pages Free Tier includes:

• 100,000 requests/day
• 500 builds/month
• D1: 5GB storage, 5 million reads/day
• KV: 100,000 reads/day, 1,000 writes/day

For most small to medium applications, the free tier is sufficient.