Skip to content

dev-bootstrap.md

Latest commit

 

History

History
143 lines (94 loc) · 2.94 KB

dev-bootstrap.md

File metadata and controls

143 lines (94 loc) · 2.94 KB

Dev Environment Bootstrap

This guide covers how to create the first real Cloudflare dev environment for this project.

Goal

Provision:

  • one D1 database
  • one R2 bucket
  • four Queues
  • one deployed Worker in env.dev

1. Log in to Cloudflare

wrangler login

2. Create Cloudflare resources

Use the template helper:

bash scripts/bootstrap_dev_resources.sh

Or run the commands manually:

wrangler d1 create mailagents-dev
wrangler r2 bucket create mailagents-dev-email
wrangler queues create mailagents-dev-email-ingest
wrangler queues create mailagents-dev-agent-execute
wrangler queues create mailagents-dev-outbound-send
wrangler queues create mailagents-dev-dead-letter

3. Copy the generated D1 database ID

When wrangler d1 create mailagents-dev succeeds, Cloudflare returns a database_id. Paste that value into:

Specifically:

  • env.dev.d1_databases[0].database_id

4. Configure SES-related values for dev

Update:

  • env.dev.vars.SES_FROM_DOMAIN
  • env.dev.vars.SES_CONFIGURATION_SET

Recommended:

  • use a dedicated dev sending subdomain
  • use a dev-only SES configuration set

Example:

  • SES_FROM_DOMAIN = "dev.mail.yourdomain.com"
  • SES_CONFIGURATION_SET = "mailagents-dev"

5. Set Worker secrets for dev

Print the commands:

bash scripts/bootstrap_worker_secrets.sh dev

Then run the printed wrangler secret put commands and enter real secret values.

6. Validate config

npm run config:check:dev

This should pass before any remote migration or deploy.

7. Apply remote dev schema

npm run d1:migrate:remote:dev
npm run d1:seed:remote:dev

8. Deploy dev

npm run deploy:dev

This deploys the existing shared Cloudflare dev worker:

  • mailagents-dev
  • https://mailagents-dev.izhenghaocn.workers.dev

Subsequent npm run deploy:dev runs update that same environment.

9. Verify deployed dev

After deploy, verify:

  • worker responds
  • /v2/meta/runtime responds
  • auth token route works if ADMIN_ROUTES_ENABLED=true
  • agent creation works
  • draft creation works
  • SES webhook endpoint is reachable

Helpful commands:

curl -sS https://mailagents-dev.izhenghaocn.workers.dev/v2/meta/runtime | jq '.server'

BASE_URL='https://mailagents-dev.izhenghaocn.workers.dev' \
ADMIN_API_SECRET_FOR_SMOKE=replace-with-admin-api-secret \
WEBHOOK_SHARED_SECRET_FOR_SMOKE=replace-with-shared-secret \
bash ./scripts/local_smoke.sh

BASE_URL='https://mailagents-dev.izhenghaocn.workers.dev' \
ADMIN_API_SECRET_FOR_SMOKE=replace-with-admin-api-secret \
bash ./scripts/mcp_smoke.sh

10. Recommended next step

Once dev works end to end:

  1. create staging
  2. disable admin/debug routes there
  3. run remote migration/seed for staging
  4. deploy staging

Notes

  • Keep staging and production admin/debug routes disabled by default.
  • Do not reuse production SES identities or configuration sets in dev.