Skip to content

PikoClaw Deployment Guide — Cloudflare Workers, D1, R2, Pages

Deployment Guide

Deploy PikoClaw to Cloudflare for production use. This guide covers Workers (API), Pages (frontend), D1 (database), and R2 (storage).

Architecture Overview

PikoClaw deployment across Cloudflare services:

  • Pages — Next.js Frontend at dev.pappas.work
  • Worker — REST API at api.pappas.work
  • D1 Database — pikoclaw-knowledge
  • R2 Storage — pikoclaw-uploads
  • Python Backend — extraction + search

Prerequisites

  • Cloudflare Account — Free tier sufficient for testing; Workers + D1 + R2 available
  • wrangler CLI — npm install -g wrangler
  • Authenticated with Cloudflare — wrangler login
  • Custom Domain (optional) — e.g., api.pappas.work, dev.pappas.work

Step 1: Set Up D1 Database

Create and configure the D1 database:

# Create the database
wrangler d1 create pikoclaw-knowledge

# Apply schema and seed data
wrangler d1 execute pikoclaw-knowledge < schema.sql
wrangler d1 execute pikoclaw-knowledge < seed-data.sql

Verify the database:

# List all databases
wrangler d1 list

# Query the database
wrangler d1 execute pikoclaw-knowledge --command "SELECT COUNT(*) FROM messages;"

Step 2: Set Up R2 Storage

Create the R2 bucket for file uploads:

# Create bucket
wrangler r2 bucket create pikoclaw-uploads

# Verify
wrangler r2 bucket list

Step 3: Deploy the API Worker

Deploy:

# Deploy to production
wrangler deploy --env production

Monitor deployment:

# View logs
wrangler tail --format pretty

# Check service status
curl https://api.pappas.work/health

Step 4: Deploy the Frontend

Build and deploy the Next.js application:

cd web
npm run build
wrangler pages deploy out/

Step 5: Custom Domains (Optional)

Route traffic to your custom domains via Cloudflare DNS:

api.pappas.work    CNAME    api.pappas.work.workers.dev
dev.pappas.work    CNAME    pikoclaw-web.pages.dev

Verify SSL:

curl -I https://api.pappas.work/health
curl -I https://dev.pappas.work

Step 6: CI/CD Pipeline

Enable automatic deployments via GitHub Actions. Configure secrets:

CLOUDFLARE_API_TOKEN       # From https://dash.cloudflare.com/profile/api-tokens
CLOUDFLARE_ACCOUNT_ID      # From wrangler whoami

Environment Variables

Variable Service Required
CLOUDFLARE_API_TOKEN All Yes
CLOUDFLARE_ACCOUNT_ID All Yes
DATABASE_ID Worker Yes
BUCKET_NAME Worker Yes
NEXT_PUBLIC_API_URL Frontend Yes
NEXT_PUBLIC_WS_URL Frontend No
ENVIRONMENT Worker No

Troubleshooting

Issue Solution
401 Unauthorized on deploy Run wrangler login and verify token in secrets
D1 database "locked" error Wait 60 seconds and retry
404 on /health endpoint Verify Worker deployment with wrangler deployments list
CORS errors on frontend Check Worker's Access-Control-Allow-Origin headers
Pages build fails Check .env.local in web/ directory

Rollback

Roll back a failed deployment:

wrangler rollback --message "Rollback due to error"
wrangler pages deployment rollback pikoclaw-web --deployment-id abc123

Next Steps

Version: 0.5.0 | Last Updated: Mar 27, 2026