☁️ Cloudflare Pages Deployment

Complete guide for deploying all GoGrab properties to Cloudflare Pages

🚀 Quick Deploy Commands

Deploy Main App (app.gograb.space)

# Build & Deploy in one command
yarn build:gograb && yarn deploy:wrangler:gograb

Deploy Individual Properties

⚠️ Docs deployment: yarn deploy:docs clears cache and builds automatically. See deployment-pitfalls.md.

📋 All GoGrab Properties

User Platform (Cloudflare)

Frontend (Cloudflare) services hosts our user platform - the services that power the GoGrab platform:

🔧 Detailed Deployment Instructions

1. Main App (app.gograb.space)

The main GoGrab Space application.

Prerequisites

# Ensure Cloudflare credentials are in .env.local
cat .env.local | grep CLOUDFLARE
# Should show:
# CLOUDFLARE_ACCOUNT_ID=xxxxx
# CLOUDFLARE_API_TOKEN=xxxxx

Build

# Production build (uses environment.prod.ts)
yarn build:gograb

Deploy

# Option 1: Using yarn script (recommended)
yarn deploy:wrangler:gograb

# Option 2: Direct wrangler command
npx wrangler pages deploy ./dist/apps/gograb-space/browser \
  --project-name=gograb-space-app \
  --branch=main \
  --commit-dirty=true

Verify Deployment

# Check pages.dev URL
curl -s -o /dev/null -w "%{http_code}" https://gograb-space-app.pages.dev/

# Check custom domain
curl -s -o /dev/null -w "%{http_code}" https://app.gograb.space/

2. Landing Page (gograb.space)

Static landing page for the main domain.

Deploy

yarn deploy:landing

Manual Deploy

npx wrangler pages deploy ./deploy/gograb-landing \
  --project-name=gograb-landing \
  --branch=main

3. Documentation (docs.gograb.space)

The docs-angular application.

⚠️ CRITICAL: Read deployment-pitfalls.md before deploying! The deployment script clears all caches to prevent stale builds.

Recommended: Single Command Deploy

# This is the safest way - clears cache, builds fresh, deploys, and verifies
yarn deploy:docs

Optional: Preview Production Build Locally First

# Build and serve production locally to test before deploying
yarn deploy:docs:preview
# Opens http://localhost:5010 with production build

Manual Steps (if needed)

# Step 1: Clear ALL caches (CRITICAL - prevents stale builds)
nx reset
rm -rf dist/apps/docs-angular

# Step 2: Build with --skip-nx-cache (forces fresh build)
yarn nx build docs-angular --configuration=production --skip-nx-cache

# Step 3: Deploy
npx wrangler pages deploy ./dist/apps/docs-angular/browser \
  --project-name=gograb-docs \
  --branch=main \
  --commit-dirty=true

# Step 4: Verify (wait 5s for edge propagation, then check)
curl -s https://docs.gograb.space/ | grep -oE 'main-[A-Z0-9]+\.js'

Why Cache Clearing Matters

In session 73, we deployed fixes but Cloudflare served stale content because:

1. NX cached old builds and served them despite code changes
2. We didn't use --skip-nx-cache
3. Production was broken while localhost worked fine

The yarn deploy:docs script now handles all of this automatically.

4. Pulse (pulse.gograb.space)

GoGrab Pulse landing and music player.

Deploy

yarn deploy:pulse

# Or manually:
npx wrangler pages deploy ./deploy/gograb-pulse \
  --project-name=gograb-pulse \
  --branch=main

5. Admin (admin.gograb.space)

GoGrab Admin dashboard application.

Deploy

# Recommended: Single command (clears cache, builds, deploys, verifies)
yarn deploy:wrangler:admin

# Or using the generic wrangler script:
./tools/scripts/deploy-with-wrangler.sh gograb-admin-app ./dist/apps/gograb-admin/browser main

NX project name: gograb-admin

6. Dev (dev.gograb.space)

GoGrab Developer tools application.

Deploy

# Recommended: Single command (clears cache, builds, deploys, verifies)
yarn deploy:wrangler:dev

# Or using the generic wrangler script:
./tools/scripts/deploy-with-wrangler.sh gograb-dev-app ./dist/apps/gograb-dev/browser main

NX project name: gograb-dev

7. AI (ai.gograb.space)

GoGrab AI admin frontend.

Deploy

# Recommended: Single command (clears cache, builds, deploys, verifies)
yarn deploy:wrangler:ai

# Or using the generic wrangler script:
./tools/scripts/deploy-with-wrangler.sh gograb-ai-app ./dist/apps/gograb-ai/browser main

NX project name: gograb-ai (same as folder name)

8. Space Admin (space-admin.gograb.space)

Space Admin management panel.

Deploy

# Recommended: Single command (clears cache, builds, deploys, verifies)
yarn deploy:wrangler:space-admin

# Or using the generic wrangler script:
./tools/scripts/deploy-with-wrangler.sh space-admin-app ./dist/apps/space-admin/browser main

NX project name: space-admin

⚙️ Environment Configuration

Critical: Production API URLs

⚠️ IMPORTANT: Production builds MUST use production API URLs, not localhost!

Correct Configuration

The project.json for each app MUST have fileReplacements in the production configuration:

{
  "configurations": {
    "production": {
      "fileReplacements": [
        {
          "replace": "apps/gograb-space/src/environments/environment.ts",
          "with": "apps/gograb-space/src/environments/environment.prod.ts"
        }
      ],
      // ... other config
    }
  }
}

API URL Mapping

Environment Files

apps/gograb-space/src/environments/
├── environment.ts          # Development (localhost)
├── environment.prod.ts     # Production (api.gograb.space)
├── environment.shared.ts   # Shared constants
└── environment.integration.ts # Integration testing

🌐 DNS Configuration

Cloudflare DNS Records

# Root domain (landing)
@       CNAME   gograb-landing.pages.dev

# Main app
app     CNAME   gograb-space-app.pages.dev

# Documentation
docs    CNAME   gograb-docs.pages.dev

# Pulse
pulse   CNAME   gograb-pulse.pages.dev

# Admin
admin   CNAME   gograb-admin-app.pages.dev

# Dev
dev     CNAME   gograb-dev-app.pages.dev

# AI
ai      CNAME   gograb-ai-app.pages.dev

# Space Admin
space-admin CNAME space-admin-app.pages.dev

# APIs (Railway)
api     CNAME   backend-api-production-97c0.up.railway.app
ai-api  CNAME   backend-ai-api-production.up.railway.app
docs-api CNAME  backend-docs-api-production.up.railway.app

Nameservers

colin.ns.cloudflare.com
kara.ns.cloudflare.com

🔄 GitHub Actions (Automatic Deployment)

Available Workflows

All workflows trigger on push to main and support workflow_dispatch (manual trigger).

Workflow Steps

1. Checkout repository
2. Setup Node.js 20
3. Install dependencies (yarn install --frozen-lockfile)
4. Build application (yarn nx build <app> --configuration=production)
5. Verify index.html exists
6. Deploy to Cloudflare Pages via cloudflare/wrangler-action@v3
7. Output deployment summary

Required Secrets

Set these in GitHub → Settings → Secrets and variables → Actions:

🛠️ Troubleshooting

"Project not found" Error

Cause: Cloudflare Pages project doesn't exist in Cloudflare.

Fix: Create the project first using wrangler:

# Create projects for all apps that need them:
npx wrangler pages project create gograb-admin-app --production-branch main
npx wrangler pages project create gograb-dev-app --production-branch main
npx wrangler pages project create gograb-ai-app --production-branch main
npx wrangler pages project create space-admin-app --production-branch main

# Or use the existing deploy script (it auto-creates on first deploy):
npx wrangler pages project create <project-name> --production-branch main

Alternatively, create them via the Cloudflare Dashboard → Pages → Create a project → Direct Upload.

Production Using localhost APIs

Cause: Missing fileReplacements in project.json production configuration.

Symptoms:

• Console shows Failed to load resource: net::ERR_CONNECTION_REFUSED
• API calls to localhost:3000 or localhost:3001

Fix: Add fileReplacements to production config in apps/APP_NAME/project.json:

"production": {
  "fileReplacements": [
    {
      "replace": "apps/APP_NAME/src/environments/environment.ts",
      "with": "apps/APP_NAME/src/environments/environment.prod.ts"
    }
  ]
}

Build Artifacts Not Found

Cause: Build output structure changed.

Fix: Verify build output exists:

ls -la dist/apps/gograb-space/browser/index.html

Deployment Takes Too Long

Cause: Large bundle size.

Fix:

1. Check bundle size: du -sh dist/apps/gograb-space/browser/
2. Cloudflare limit is 25MB per deployment
3. Optimize if needed: remove unused dependencies, enable tree-shaking

📊 Project Configuration

Account Details

Projects

🧪 Testing Deployments

Verify API Configuration

After deployment, check the browser console:

// Should NOT see localhost URLs in production
// ❌ Bad: http://localhost:3000/api/...
// ✅ Good: https://api.gograb.space/api/...

Health Check Endpoints

# Main API
curl https://api.gograb.space/api/health

# AI API
curl https://ai-api.gograb.space/ai-api/health

# Docs API
curl https://docs-api.gograb.space/docs-api/health

Full E2E Test

yarn e2e:pipeline

📁 Related Files

🔗 See Also

• Railway Deployment - Backend APIs
• Environment Variables - All env vars
• Quick Commands - Command reference
• Cloudflare Pages Docs