Codflow Setup

CodFlow Setup — Agent Runbook

CodFlow is a cash-on-delivery (COD) e-commerce platform built on Cloudflare Workers, Astro 7 (dashboard + storefront), and D1 SQLite. This runbook takes a fresh clone to a fully working, verified deployment.

Every setup creates real Cloudflare resources in the developer's account, binds their real IDs into the wrangler.toml files, and migrates and seeds that same database. There is exactly one path — follow it in order and do not skip a gate.

The dashboard is cod-client-astro (Astro, prerendered static + auth worker). (The legacy Next.js dashboard was removed in v1.1.x.)

Before Starting — State This Contract

State this to the developer before running anything:

"This setup will create D1 <project>-db, R2 bucket <project>-images, and two KV namespaces in your Cloudflare account <account>, bind their real IDs into both wrangler.toml files, and migrate + seed the D1 database in your account. Nothing is left on placeholder values."

Both cod-server/wrangler.toml and cod-client-astro/wrangler.toml ship with all-zero placeholder resource IDs. After Step 3 of this runbook, no placeholder may remain anywhere in either file — deploys fail or silently break with placeholders.

Prerequisites

• Node.js ≥ 22.12 and npm.
• Cloudflare authentication:

  npx wrangler whoami    # if not logged in: npx wrangler login (browser OAuth)
  

• R2 must be enabled on the account (requires a payment card on file, free tier): confirm dash.cloudflare.com → R2 shows enabled before creating buckets.
• Ports 4321 / 8787 free if services will run locally:

  lsof -nP -iTCP:4321 -iTCP:8787 -sTCP:LISTEN   # expect no output
  

  Processes on these ports often belong to ANOTHER checkout's dev servers; identify via ps -p <pid> and confirm with the human before killing.

If whoami lists multiple accounts, ask the developer which one to use and record that account_id.

CRITICAL: Strip stale CLOUDFLARE_ACCOUNT_ID everywhere. If the shell exports CLOUDFLARE_ACCOUNT_ID for an account the OAuth token cannot access, every wrangler command fails with Authentication error [code: 10000] — including npm scripts (which invoke wrangler) and seeders. Shell rc files re-export this variable in every new shell. Prefix EVERY wrangler invocation with env -u CLOUDFLARE_ACCOUNT_ID so it targets the logged-in account, or unset CLOUDFLARE_ACCOUNT_ID once per session. Examples throughout this runbook show the prefix inline where practical.

Step 1 — Install Dependencies (one command)

CodFlow is an npm workspace monorepo: one root package.json, one root package-lock.json. Never create per-package lockfiles.

npm ci        # at the repo root — installs all workspaces

Sanity check (optional): npm ls vite must show a single Vite major across all workspaces (the root overrides pin enforces it).

Step 2 — Create Dedicated Cloudflare Resources

Create fresh, dedicated resources for this CodFlow install. Default project name is codflow; use the developer's preferred prefix (<project>) otherwise.

env -u CLOUDFLARE_ACCOUNT_ID npx wrangler d1 create <project>-db                  # capture database_id
env -u CLOUDFLARE_ACCOUNT_ID npx wrangler r2 bucket create <project>-images
env -u CLOUDFLARE_ACCOUNT_ID npx wrangler kv namespace create RATE_LIMIT          # capture id
env -u CLOUDFLARE_ACCOUNT_ID npx wrangler kv namespace create OAUTH_KV            # capture id (MCP OAuth)

Rules:

• Always create new resources for this setup. Never bind to a resource that already exists in the account — it may belong to another application or store, and running migrations/seed against it would write into foreign data.
• Unique names apply to WORKER names, not just resources. Default worker name fields in wrangler configs collide across clones, and deploying silently overwrites another installation. Require the developer to choose a unique prefix (e.g. mystore-server, mystore-dashboard, mystore-theme01) and update the name field in all three wrangler files before first deploy. This prevents cross-clone overwrite.
• If a resource name is taken, do not reuse the existing resource: choose a fresh, unique name (e.g. append the store name or a short suffix) and create again.
• Capture the D1 database_id (UUID) and both KV ids (32-hex) from command output. If parsing fails → hard stop, print the raw output, ask the developer. Never fall back to placeholder values.
• Create two KV namespaces (rate limiting + MCP OAuth provider). Binding names differ per file: cod-server uses RATE_LIMIT + OAUTH_KV; cod-client-astro uses RATE_LIMIT_KV (its own namespace, only the id matters).

Step 3 — Bind Real IDs into BOTH wrangler.toml Files

cp cod-server/wrangler.toml.example cod-server/wrangler.toml
cp cod-client-astro/wrangler.toml.example cod-client-astro/wrangler.toml

Files: cod-server/wrangler.toml and cod-client-astro/wrangler.toml.

• [[d1_databases]]: set database_id (same database in both files).
• [[kv_namespaces]]: set ids.
• [[r2_buckets]]: confirm bucket_name matches the bucket created in Step 2.

Then read both files back and verify no placeholder remains anywhere, including [env.production] blocks:

grep -rn "00000000-0000\|00000000000000000000000000000000" \
  cod-server/wrangler.toml cod-client-astro/wrangler.toml
# expected: no matches — fix any hit before continuing

Set the D1 database name once: the scripts are not hardcoded — the seeders, the migration wrapper (cod-server/scripts/d1.mjs) and the R2 setup all read COD_DB_NAME from <repo-root>/.env via cod-server/scripts/cloud-env.mjs (precedence: process.env > .env > default). Set it there:

cp .env.example .env      # at the repo root
# COD_DB_NAME=<your database name>
# COD_SERVER_URL=https://<your api domain>  # required BEFORE theme01 deploy —
#   npm run deploy refuses a localhost value (the default) without --force-local

The database_name / database_id in each wrangler.toml still has to match the database you created — those are wrangler's own config, not script input. Confirm no script or config still pins the sample name:

grep -r "codflow-os-db" --exclude-dir=node_modules --exclude-dir=.git
# expected: only .env.example defaults and documentation, zero script hits

Confirm the filled wrangler.toml files are not tracked by git:

git status cod-server/wrangler.toml cod-client-astro/wrangler.toml
# expected: nothing listed (both ignored)

If either file appears in git status, stop — the .gitignore is not applied correctly. Do not continue until both are untracked.

While editing, also replace the example domains in [vars] / [env.production.vars] (WORKER_URL, BETTER_AUTH_URL, WORKER_SELF_URL, PUBLIC_APP_URL, PUBLIC_API_URL, PUBLIC_TRUSTED_ORIGINS) with the developer's real URLs when they are known; localhost defaults are correct for local runs. The storefront's COD_SERVER_URL is NOT set in cod-astro/theme01/wrangler.jsonc — it is injected at deploy time by npm run deploy from COD_SERVER_URL in the root .env.

Also create the dashboard's build-time client env:

cd cod-client-astro && cp .env.example .env
# edit .env → PUBLIC_API_URL is the cod-server URL (baked in at build time)

Step 3b — Configure R2 for Image Uploads

This step requires values only the developer can retrieve from the Cloudflare dashboard. The agent must ask for them — do not guess or skip.

Agent instructions

Ask the developer for these four things before proceeding:

1. The media subdomain they want to use for serving images (e.g. media.yourdomain.com). They must add this as a custom domain on the R2 bucket first:

   Cloudflare dashboard → R2 → <project>-images → Settings → Custom Domains → Connect Domain → enter the subdomain → wait for Active.

2. Their Cloudflare Account ID (Cloudflare dashboard → top-right account menu, or any Workers page sidebar).

3. An R2 API token created specifically for this bucket:

   Cloudflare dashboard → R2 → Manage R2 API Tokens → Create API Token → Permissions: Object Read & Write → Bucket: <project>-images → Create.

   This shows two values once — copy both:

   • Access Key ID
   • Secret Access Key

Once the developer provides all four values, continue with the steps below.

1. Give the developer the CORS JSON to paste

Tell the developer to set the CORS policy on the bucket manually:

Cloudflare dashboard → R2 → <project>-images → Settings → CORS Policy → Add CORS policy → paste this JSON (replacing the dashboard domain):

[
  {
    "AllowedOrigins": [
      "https://<dashboard-domain>",
      "http://localhost:4321"
    ],
    "AllowedMethods": ["PUT", "GET", "HEAD"],
    "AllowedHeaders": ["Content-Type", "Content-Length"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

Wait for the developer to confirm it is saved before continuing.

2. Set MEDIA_DOMAIN in wrangler.toml

Update MEDIA_DOMAIN in cod-server/wrangler.toml [vars] and [env.production] to the media subdomain the developer provided. No scheme — hostname only:

MEDIA_DOMAIN = "media.yourdomain.com"

3. Set R2 secrets on the cod-server worker

After cod-server is deployed (Step 6), set the three secrets using the values the developer provided. Use stdin redirect — never echo secrets into the shell:

printf '<CF_ACCOUNT_ID>' | env -u CLOUDFLARE_ACCOUNT_ID npx wrangler secret put CF_ACCOUNT_ID --name <server-worker-name>
printf '<R2_ACCESS_KEY_ID>' | env -u CLOUDFLARE_ACCOUNT_ID npx wrangler secret put R2_ACCESS_KEY_ID --name <server-worker-name>
printf '<R2_SECRET_ACCESS_KEY>' | env -u CLOUDFLARE_ACCOUNT_ID npx wrangler secret put R2_SECRET_ACCESS_KEY --name <server-worker-name>

Also add them to cod-server/.dev.vars for local dev:

CF_ACCOUNT_ID=<value>
R2_ACCESS_KEY_ID=<value>
R2_SECRET_ACCESS_KEY=<value>
MEDIA_DOMAIN=media.yourdomain.com

4. Set MEDIA_DOMAIN on the storefront worker and redeploy

After theme01 is deployed (Step 6):

printf 'media.yourdomain.com' | env -u CLOUDFLARE_ACCOUNT_ID npx wrangler secret put MEDIA_DOMAIN --name <theme01-worker-name>
cd cod-astro/theme01 && env -u CLOUDFLARE_ACCOUNT_ID npm run deploy

5. Redeploy cod-server with updated MEDIA_DOMAIN

cd cod-server && env -u CLOUDFLARE_ACCOUNT_ID npm run deploy

Verify

# presignedUrl must appear and publicUrl must start with https://media.yourdomain.com/
curl -s -X POST https://<api-domain>/api/images/presign \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <admin-api-key>" \
  -d '{"contentType":"image/jpeg"}'

If publicUrl starts with the Worker URL instead of the media domain, MEDIA_DOMAIN is not set or the worker was not redeployed after setting it.

Step 4 — Generate Keys & Configure Secrets

Generate the keys once and keep them:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"   # BETTER_AUTH_SECRET
node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))" # STORE_API_KEY
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"       # MCP_LOGIN_TICKET_SECRET

Deploy workers BEFORE setting secrets: In non-interactive sessions, wrangler secret put against a nonexistent worker fails or hangs on the create prompt. Either deploy each worker first (Step 6), or wait until after deploy to set secrets. When setting secrets, provide values via stdin redirect from a chmod-600 temp file — never use echo or heredocs, which leak secrets into shell history and process lists:

# After cod-server is deployed:
cd cod-server
echo "<BETTER_AUTH_SECRET_value>" > /tmp/secret.txt && chmod 600 /tmp/secret.txt
env -u CLOUDFLARE_ACCOUNT_ID npx wrangler secret put BETTER_AUTH_SECRET < /tmp/secret.txt
echo "<MCP_LOGIN_TICKET_SECRET_value>" > /tmp/secret.txt
env -u CLOUDFLARE_ACCOUNT_ID npx wrangler secret put MCP_LOGIN_TICKET_SECRET < /tmp/secret.txt
rm /tmp/secret.txt

# After cod-client-astro is deployed — SAME two values (must match cod-server):
cd ../cod-client-astro
echo "<BETTER_AUTH_SECRET_value>" > /tmp/secret.txt && chmod 600 /tmp/secret.txt
env -u CLOUDFLARE_ACCOUNT_ID npx wrangler secret put BETTER_AUTH_SECRET < /tmp/secret.txt
echo "<MCP_LOGIN_TICKET_SECRET_value>" > /tmp/secret.txt
env -u CLOUDFLARE_ACCOUNT_ID npx wrangler secret put MCP_LOGIN_TICKET_SECRET < /tmp/secret.txt
rm /tmp/secret.txt

# theme01: STORE_API_KEY (same string the seeder will hash in Step 5)

For services that will also run locally, create .dev.vars from each package's .dev.vars.example with the same key values (.dev.vars is gitignored).

Keep STORE_API_KEY at hand: Step 5 seeds its hash into the database, so the storefront secret and the seeded hash must come from the identical string.

Step 5 — Migrate & Seed the Cloudflare D1 Database

Remote migrations are mandatory. All schema and demo data go against the D1 created in Step 2 (remote), not an emulated copy. Both local and remote migrations must run:

cd cod-server
env -u CLOUDFLARE_ACCOUNT_ID npm run db:migrate:local   # REQUIRED first: seed-admin writes local + remote
env -u CLOUDFLARE_ACCOUNT_ID npm run db:migrate:remote  # MANDATORY: deployed sign-in 500s without this
env -u CLOUDFLARE_ACCOUNT_ID STORE_API_KEY=<generated-store-key> npm run db:seed:remote   # demo store متجر التطوير + catalog

cd ../cod-client-astro
ADMIN_EMAIL=admin@example.com ADMIN_NAME=Admin npm run seed:admin:remote

Notes:

• db:migrate:local must run before seed-admin: the script seeds the emulated local D1 first and needs its schema to exist.
• db:migrate:remote is MANDATORY before any deployed sign-in attempt — without it, Better Auth 1.7 schema requirements fail (field "alg" does not exist in "jwkss"), producing 500 errors.
• The seeder writes better-auth ≥ 1.7 credential rows (issuer = 'local:credential', account_id = user id) — re-run it after any password reset request for the seeded admin.
• Verify the seeder reports all statements executed and note the admin email/password and API key output — they appear once.

Step 6 — Deploy in Dependency Order + Smoke Test

cd cod-server           && env -u CLOUDFLARE_ACCOUNT_ID npm run deploy
cd ../cod-client-astro  && env -u CLOUDFLARE_ACCOUNT_ID npm run deploy     # wrangler deploy (build first: npm run build)
cd ../cod-astro/theme01 && env -u CLOUDFLARE_ACCOUNT_ID npm run deploy     # astro build && wrangler deploy

After deploy, replace localhost URL vars with real deployed URLs and redeploy: Once workers are live, set PUBLIC_APP_URL / PUBLIC_API_URL / PUBLIC_TRUSTED_ORIGINS (cod-client-astro wrangler.toml [vars]), WORKER_URL, WORKER_SELF_URL, BETTER_AUTH_URL (cod-server wrangler.toml [vars]), and COD_SERVER_URL (root .env — the theme01 deploy script reads it) to the actual deployed URLs, then redeploy affected workers. For the dashboard also update .env (PUBLIC_API_URL) and rebuild — it is baked into the client bundle at build time. Skipping this causes browser sign-in failures (R6/R7).

Smoke-test after each deploy; do not continue past a failing check:

CRITICAL — Origin header in sign-in tests: Plain curl omits the Origin header; Better Auth skips its origin check and returns 200, while every real browser request gets 403 INVALID_ORIGIN (which the UI masks as "Invalid email or password"). The canonical sign-in check MUST send -H "Origin: https://<dashboard-url>" and expect 200 + user JSON. If browser login fails but curl without Origin passes, the dashboard origin is missing from PUBLIC_TRUSTED_ORIGINS — apply R6, redeploy, and retest with the Origin header.

Diagnose unclear failures with wrangler tail: Run env -u CLOUDFLARE_ACCOUNT_ID npx wrangler tail <worker-name> --format pretty in the background, have the human retry the failing operation, then read the log — the true error surfaces there, not in UI text.

workers.dev limitation (error 1042): Cloudflare blocks Worker→Worker fetch() between two *.workers.dev hosts. A storefront deployed to workers.dev cannot load products from a cod-server also on workers.dev. For a production storefront, put cod-server on a custom domain/route and point COD_SERVER_URL at it (or wire a Service Binding), then re-deploy theme01 and confirm /products shows the seeded catalog. Local development is unaffected.

Step 6b — Optional: Transactional Email (Sendili)

Offer this to the developer after the smoke tests pass; skip entirely if they decline — the feature is inert by default (no store_email_config row).

1. Ask the developer to: create a sendili.com account, buy credits, verify their sending domain (DNS records in the Sendili dashboard), and create an API key (sk_live_…).
2. In the deployed dashboard: sign in as admin → Settings → Email Sending → paste the key (domains auto-load) → set the from address by typing the local part (support, notify…) and picking the verified domain → toggle Enable email sending → Save.
3. Verify: Test connection shows Connection OK with the domain listed; then invite a team member with an email the developer can check and confirm the invite email arrives (sign-in link + temporary password), and that the invited member can sign in.
4. Docs: docs/EMAIL-SENDING.md (feature guide) and docs/adr/0001-sendili-key-at-rest.md (key storage decision).

No wrangler secrets, no worker config — the key lives in D1 (store_email_config, applied by migration 0013 in Step 5) and is masked in every API response.

Step 7 — Closing Summary (Mandatory)

Print a resource inventory:

Tell the developer how to get future updates: "When CodFlow publishes an update, just ask your AI agent to 'update CodFlow' — it will follow the codflow-update runbook (shipped in this repo), which pulls the latest code from https://github.com/bighadj22/codflow main, merges it into this install without re-running setup, keeps your resources, secrets, and data intact, and redeploys. You never repeat this runbook from scratch."

Credentials file delivery (mandatory): Write credentials to a chmod-600 markdown file OUTSIDE git-tracked directories (e.g. ~/codflow-credentials.md or /tmp/codflow-setup-<timestamp>.md). Place every value inside a fenced code block so humans can copy-paste them without trailing-space login failures. Extract values programmatically from .dev.vars or source files; never retype from memory. Delete temporary secret files afterward. Show credentials in chat output at most once.

Example credentials file structure:

# CodFlow Setup Credentials — <project-name>

## Admin User
- **Email:** `admin@example.com`
- **Password:**

API Keys

• BETTER_AUTH_SECRET:

  <base64-value>
  

• MCP_LOGIN_TICKET_SECRET:

  <hex-value>
  

• STORE_API_KEY:

  <base64url-value>
  

Deployed URLs

• Dashboard: https://
• API Server: https://
• Storefront: https://

Security: This file contains sensitive credentials. Store it securely and delete after transferring values to a password manager.

---

## Running the Stack Locally During Development

The `npm run dev` scripts execute Workers on the local machine with
Miniflare-emulated storage persisted to `<repo-root>/.wrangler-shared` — they
do not read the deployed D1. To boot all three services locally:

```bash
cd cod-server && npm run db:migrate:local && STORE_API_KEY=<key> npm run db:seed:local
cd ../cod-client-astro && ADMIN_EMAIL=… ADMIN_NAME=Admin npm run seed:admin

Then start one terminal per service:

Localhost→localhost is unaffected by the workers.dev limitation: the storefront renders the full seeded catalog locally.

The storefront directory is cod-astro/theme01 — bare cod-astro/ has no scripts.

Troubleshooting