Deployment Guide — SONAN DIGITAL Docs

XYZ Aquarium Cleaning Services

Deployment Guide

Step-by-step: D1 migrations, Worker deploy, Pages build and deploy

⚠ All terminal commands must be run from Windows terminal in the project directory (E:\Claude_Projects\sonan-trackersquarium-portal\), NOT from the AI sandbox. The sandbox gets 403 on Cloudflare pushes.

First-Time Setup
Routine Deploy (Code Changes)
Worker-Only Deploy
Database Migrations
Troubleshooting

First-Time Setup

This is a one-time step for a fresh machine or new repo clone. Skip if you've done this before.

# 1. Install dependencies
cd E:\Claude_Projects\sonan-trackersquarium-portal
npm install

# 2. Verify wrangler is authenticated
npx wrangler whoami

# 3. Run the D1 schema migration
npx wrangler d1 execute aquarium_db --file migrations/001_init.sql

# 4. Seed settings (run once to create the settings row)
npx wrangler d1 execute aquarium_db --command "INSERT OR IGNORE INTO settings (id, business_name, invoice_prefix, invoice_next_number) VALUES (1, 'XYZ Aquarium Cleaning Services', 'INV-', 1)"

Routine Deploy (Code Changes)

After making changes and committing via git (see AI Handoff for the git pattern):

# 1. Build the React app
npm run build

# 2. Deploy to Cloudflare Pages
npx wrangler pages deploy dist --project-name aquarium-portal --branch main

Cloudflare Pages deploys typically take 30–60 seconds. The live site at xyzaquarium.sonandigital.com updates automatically — no DNS changes needed.

💡 Use --branch main not --env aquarium. The --env flag maps to named environments in wrangler.toml which aren't configured for Pages in this project.

Worker-Only Deploy

Only needed when worker/index.ts (the API) changes. Frontend-only changes don't require this.

npx wrangler deploy worker/index.ts --name aquarium-api

The Worker is deployed to xyzaquarium-api.sonandigital.com. Changes are live within seconds.

Database Migrations

D1 migrations are SQL files in migrations/. Run them when the schema changes (new columns, new tables).

# Run a migration file against production D1
npx wrangler d1 execute aquarium_db --file migrations/002_add_column.sql

# Run a one-off SQL command
npx wrangler d1 execute aquarium_db --command "ALTER TABLE jobs ADD COLUMN notes2 TEXT"

# Query data to verify
npx wrangler d1 execute aquarium_db --command "SELECT COUNT(*) FROM jobs"

⚠ D1 migrations are not transactional in the same way as PostgreSQL. There is no rollback. Test schema changes against a local D1 first with --local flag before running against production.

Troubleshooting

Symptom	Fix
`git push` fails with "does not appear to be a git repository"	`.git/config` is corrupted. Delete `.git\config.lock`, recreate `.git\config` with core section, re-add remote. See AI Handoff page for full steps.
Wrangler: "You must be logged in"	Run `npx wrangler login` and authenticate in the browser
Pages deploy: "Project not found"	Verify project name: `aquarium-portal` (exact)
Pages deploy: `--env` flag error	Use `--branch main` not `--env`
API returns 403	Check `ALLOWED_ORIGIN` in wrangler.toml — must match the exact origin making the request
Build fails: TypeScript error	Run `npm run build` locally, read the error, fix the type issue in the flagged file
D1 query returns empty	Verify you're running against the right database: `npx wrangler d1 list`
Logo not showing on PDF	Logo is stored as base64 in settings. Re-upload via Settings → Logo in the admin portal.

Contents