Skip to content

Platform-sandbox — signup, email, and hub provision ​

Chain ​

text
Stripe webhook (POST /api/stripe/webhook)
  → platformBilling (D1 site_billing, customer welcome email via Resend)
  → platformBillingRegistry (HUB_REGISTRY_QUEUE)
  → platformBillingProvision (HUB_PROVISION_QUEUE)
  → lovely-home-hub-jobs-sandbox Worker
  → GitHub workflow_dispatch (platform-site-registry.yml / hub-provision-dispatch.yml)

Operator signup notify email is sent from the marketing signup API when checkout starts. Customer welcome email is sent from the Stripe webhook (checkout.session.completed or customer.subscription.created). If Resend is missing, welcome mail is skipped (webhook still succeeds). If Resend rejects the customer message, the webhook fails and provision will not run.

Common failures ​

SymptomLikely causeFix
Signup works, operator email onlyWebhook URL wrong or Access blocking StripeStripe Dashboard → test webhook https://platform-sandbox.lovely-home.co.uk/api/stripe/webhook (not /api/platform/…). Terraform platform_stripe_webhook bypass on that path.
QUEUE_NOT_CONFIGURED / no GitHub runsPages missing queue producersterraform apply with sandbox-hub.tfvars against platform-sandbox.tfstate. Wrangler deploy alone does not bind HUB_PROVISION_QUEUE.
Queue send OK, no GitHub dispatchlovely-home-hub-jobs-sandbox missing token or consumerSet platform_github_token in tfvars; ensure manage_hub_queue_consumers = true in sandbox-hub.tfvars (not copied false from prod import), then terraform apply.
Registry jobs retry forever (sandbox)Worker treated -sandbox registry queue as provision queueFixed in hub-jobs: queue names containing hub-registry / hub-provision. Redeploy Worker via Terraform apply.
Provision skipped (site_not_in_manifest)Site id not in filtered sandbox manifest / sites.yamlSandbox deploy sets PLATFORM_MANIFEST_SANDBOX=1 (default allowlist: sandbox, test, practice — not demo). Paid signups appear in platform admin from billing before git registry; use disposable test slugs. Override with PLATFORM_MANIFEST_SANDBOX_SITES.

Verify ​

bash
bash scripts/verify-sandbox-provision-chain.sh

Requires CLOUDFLARE_API_TOKEN and terraform/environments/sandbox-hub.tfvars (or env vars). Checks Pages queue bindings (*-sandbox names), hub-jobs Worker PLATFORM_GITHUB_TOKEN, queue consumers, and live /api/public/signup/status blockers.

Terraform checklist (sandbox) ​

  1. backend.hcl key home-dashboard/platform-sandbox.tfstate
  2. platform_resource_suffix = "sandbox"
  3. platform_github_token, resend_api_key, Stripe test keys + webhook secret
  4. github_production_branch = "sandbox" (optional — workflow dispatch ref)
  5. terraform apply -var-file=environments/sandbox-hub.tfvars -var=terraform_stack=platform
  6. Deploy Pages: bash scripts/deploy-sandbox-lovely-home.sh (sets LOVELY_STACK=sandbox, sandbox manifest filter)

See also sandbox-promotion-model.md and sandbox-hub-quickstart.md.