Sandbox hub — operator quickstart
Minimal flow to stand up marketing-sandbox + platform-sandbox (Stripe test signup/provision) without touching production platform.tfstate.
Provision chain and failure modes: sandbox-provision-chain.md.
Step 1 — Generate sandbox-hub.tfvars
From repo root, with terraform/environments/hub.tfvars already filled for production:
node scripts/init-sandbox-hub-tfvars.mjs- Writes
terraform/environments/sandbox-hub.tfvars(gitignored). - Copies Cloudflare ids, operator emails, and uncommented secrets from hub.tfvars, then patches sandbox hostnames,
platform_resource_suffix = "sandbox", andsites = {}. - Sets
manage_hub_queue_consumers = true(sandbox state is separate from prod — consumers must exist). - If hub.tfvars is missing, falls back to
hub.tfvars.exampleorsandbox-hub.tfvars.example(replaceYOUR_*before apply).
Re-run after hub.tfvars changes:
node scripts/init-sandbox-hub-tfvars.mjs --forceManual: cp terraform/environments/sandbox-hub.tfvars.example terraform/environments/sandbox-hub.tfvars and edit.
Do not add sites.sandbox to this file — sandbox.lovely-home.co.uk stays in production platform.tfstate via sandbox.tfvars.
Step 2 — Backend (platform-sandbox.tfstate)
cp terraform/environments/backend.hcl.example terraform/environments/backend.hclIn terraform/environments/backend.hcl (never commit):
There is no committed prod backend.hcl in git (only backend.hcl.example; real file is gitignored on your laptop). Use one local file, or two side-by-side configs (recommended):
backend.platform.hcl—key = "home-dashboard/platform.tfstate"backend.platform-sandbox.hcl—key = "home-dashboard/platform-sandbox.tfstate"
Same bucket + endpoints.s3 in both. Pass the file you need:
terraform init -reconfigure -backend-config=environments/backend.platform-sandbox.hcl
Do not cp backend.hcl.example backend.hcl if you already had a working file — that replaces real bucket/endpoint with placeholders. If you did, rebuild from Cloudflare R2 (bucket name + account endpoint) and GitHub secrets TF_STATE_R2_* (same values prod CI uses).
bucket = "lovely-home-terraform-state" # same real bucket name as prod
key = "home-dashboard/platform-sandbox.tfstate" # only line that differs from prod apply
endpoints = {
s3 = "https://<your-real-account-id>.r2.cloudflarestorage.com"
}Export R2 credentials for Terraform state (same token as prod — not a separate sandbox pair):
export AWS_ACCESS_KEY_ID="..." # R2 token — TF_STATE_R2_ACCESS_KEY_ID in GitHub
export AWS_SECRET_ACCESS_KEY="..." # TF_STATE_R2_SECRET_ACCESS_KEYStep 3 — Terraform init / apply
export CLOUDFLARE_API_TOKEN="..." # Workers/Pages/D1/Access write — not stored in tfvars
cd terraform
terraform init -reconfigure -backend-config=environments/backend.hcl
terraform fmt -check -recursive
terraform validate
terraform plan -var-file=environments/sandbox-hub.tfvars -var=terraform_stack=platform
terraform apply -var-file=environments/sandbox-hub.tfvars -var=terraform_stack=platformApply errors (common)
| Error | Fix |
|---|---|
20217 exceeded maximum number of zone rulesets for phase http_ratelimit | Set public_signup_edge_rate_limit_enabled = false in sandbox-hub.tfvars (prod already has the one zone ruleset). App-level signup limits still apply. |
12130 domain does not belong to zone on Access | Create a proxied CNAME platform-sandbox → your sandbox Pages *.pages.dev host before Access apps, or finish Pages custom domain until Active, then re-apply. Optional: pages_preview_deployments_enabled = false in tfvars. |
After apply: Stripe Dashboard (test mode) webhook →https://platform-sandbox.lovely-home.co.uk/api/stripe/webhook
Step 4 — GitHub secrets (deploy workflow)
Deploy sandbox Lovely Home (manual workflow) only needs:
gh secret list --repo marklovely/home-dashboard | rg CLOUDFLARE_API_TOKEN
# Must be set: CLOUDFLARE_API_TOKENTerraform apply is local — it uses sandbox-hub.tfvars + shell env, not GitHub Actions secrets.
| Local apply | Source |
|---|---|
CLOUDFLARE_API_TOKEN | Your shell (same token class as GitHub CLOUDFLARE_API_TOKEN) |
| R2 state | AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (or GitHub TF_STATE_R2_*) |
| Stripe / Turnstile / Resend / platform tokens | sandbox-hub.tfvars (copied from hub.tfvars by init script) |
Optional GitHub Environment sandbox with SANDBOX_* secrets is only if you later wire CI to apply sandbox Terraform; the current deploy workflow does not read tfvars.
Production Platform admin Terraform secrets are unchanged.
Step 5 — Deploy app code
Marketing-sandbox URL is not tied to your PR
https://marketing-sandbox.lovely-home.co.uk does not auto-update when you open or merge a feature PR. What you see there is whatever was last deployed to the lovely-home-sandbox Pages project.
| Source | When marketing-sandbox updates |
|---|---|
Push to sandbox branch | CI workflow Deploy sandbox on push (.github/workflows/deploy-sandbox-on-push.yml) |
| Manual Deploy sandbox Lovely Home | Only when someone runs the workflow (see below) |
| Feature branches | Never unless you deploy that branch explicitly |
If marketing looks stuck on an old layout or version.json (e.g. v3.4.0), the live site is almost certainly still serving an old deploy — not your current PR branch.
Custom domain vs preview branch (marketing-sandbox)
https://marketing-sandbox.lovely-home.co.uk (and lovely-home-sandbox.pages.dev without a branch prefix) serves the Cloudflare Pages project Production branch — by default main, matching github_production_branch in Terraform unless you changed it in the dashboard.
| Deploy target | What updates |
|---|---|
wrangler pages deploy --branch main (default in deploy-sandbox-lovely-home.sh) | Custom domain + Production alias |
wrangler pages deploy --branch sandbox (old default / PAGES_BRANCH=sandbox) | Preview alias only, e.g. https://sandbox.lovely-home-sandbox.pages.dev |
After deploy, the script compares staged version.json to curl -sS https://marketing-sandbox.lovely-home.co.uk/version.json. A mismatch usually means the deploy went to a preview branch while the custom domain still points at an older Production deploy.
platform-sandbox works the same way (#1127). The script asks Cloudflare for home-dashboard-platform-sandbox's production branch and deploys there, whatever PAGES_BRANCH says. It then checks that the deployment serving platform-sandbox.lovely-home.co.uk is the commit it just deployed, and fails if it isn't. This needs CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. Without them (a laptop deploy using OAuth), it deploys to PAGES_BRANCH and prints a warning that the result wasn't checked.
Environment variables:
| Variable | Default | Purpose |
|---|---|---|
SANDBOX_MARKETING_PAGES_PRODUCTION_BRANCH | main | Branch that owns the custom domain |
SANDBOX_MARKETING_PAGES_PREVIEW_BRANCH | (empty) | Optional second deploy (e.g. sandbox) for a preview alias |
Immediate fix when live site stuck on v3.4.0 but preview shows v3.6.0:
SANDBOX_MARKETING_PAGES_PRODUCTION_BRANCH=main LOVELY_STACK=sandbox bash scripts/deploy-sandbox-lovely-home.shWays to preview marketing from a feature branch (e.g. PR #697 feature/marketing-offline-guest-help):
Local deploy (recommended for quick iteration) — check out the branch, then deploy (OAuth; unset API token):
bashgit checkout feature/marketing-offline-guest-help unset CLOUDFLARE_API_TOKEN bash scripts/deploy-sandbox-lovely-home.shGitHub Actions manual deploy — Actions → Deploy sandbox Lovely Home → confirm
deploy-sandbox→ set git_ref to your branch (default ismain, which does not match an open PR). Example:feature/marketing-offline-guest-help.Merge or push to
sandbox— updates marketing-sandbox via CI on the next push to that branch (shared long-lived sandbox branch; do not use this only to test one PR unless the team agrees).
After any sandbox marketing deploy, the purple SANDBOX — marketing stack banner includes a short git SHA (e.g. · 41bad0a) so you can confirm which commit is live. Footer v version comes from version.json on that same deploy.
Troubleshooting — footer still shows v3.4.0 (or old layout) after deploy
The deploy script now fails before Wrangler if staged version.json is missing, below 3.6.0, or does not match package.json. If the live site still looks stale, Cloudflare is likely serving an old Pages deploy or you deployed from the wrong checkout.
From the branch you intend to ship (e.g. PR #697):
git rev-parse HEAD
cat website/version.json
curl -sS https://marketing-sandbox.lovely-home.co.uk/version.json| Check | Expected |
|---|---|
website/version.json | Same as root package.json (e.g. 3.6.0 on current main) |
Live curl …/version.json | Matches your deploy commit after Wrangler finishes |
| Git branch | At least the merge-base with main that includes marketing pricing/layout fixes (#696+); rebase or merge origin/main if your branch predates that work |
Inspect staging without deploying:
npm run stage-marketing-sandbox
cat dist-marketing-sandbox/version.jsonAfter bash scripts/deploy-sandbox-lovely-home.sh, confirm:
curl -sS https://marketing-sandbox.lovely-home.co.uk/version.jsonLocal (OAuth for Pages):
Check out the branch you intend to preview (e.g. git checkout feature/marketing-offline-guest-help for PR #697). deploy-sandbox-lovely-home.sh deletes and rebuilds dist-marketing-sandbox/ from website/ on every run — you do not deploy the old committed dist unless you skip that script.
unset CLOUDFLARE_API_TOKEN
bash scripts/deploy-sandbox-lovely-home.shGitHub Actions: workflow Deploy sandbox Lovely Home → confirm with deploy-sandbox → optional git_ref (branch/SHA to checkout before deploy; default main).
Then:
PLATFORM_BILLING_D1_NAME=lovely-home-platform-billing-sandbox \
node scripts/apply-platform-billing-migration.mjsPlatform UI → Settings → Stripe mode → test.
How sandbox hubs find the sandbox platform
Since #841, each hub is stamped with its platform at provision. sync-wrangler-from-terraform.mjs runs before the Worker deploy. It asks production, then sandbox, GET /api/public/hub-status/{site_id}, and writes PLATFORM_API_ORIGIN into [env.{site_id}.vars] for whichever platform has billing for the hub. The registry overlay carries it to main, so CD redeploys keep it.
- The hub Worker then calls only that platform (
fetchHubPlatforminworker/src/lib/hubPlanLimits.js). - The Worker keeps a confirmed
hub-plan-statusanswer for 30 seconds per site and platform (PLAN_STATUS_CACHE_MS, #1388), so one hub open makes at most one platform call. A plan change shows within 30 seconds on a warm Worker and at once on a cold one. Failed andbillingKnown: falseanswers are not kept; the last confirmed plan in D1 (#917) still covers outages. - The browser asks its own Worker once (
GET /api/hub-platform) and does the same (src/services/hubPlatformFetch.js). - To force a value, set
HUB_PLATFORM_API_ORIGINin the provision environment.HUB_PLATFORM_API_ORIGIN_DETECT=0skips detection.
Older hubs, and operator hubs with no billing (demo), aren't stamped and keep the runtime fallback. Hub-facing calls go to production first: plan and limits (hub-plan-status), the trial watermark (hub-trial-status) and the signup use case (hub-signup-use-case). Those endpoints return billingKnown. When production says false, the hub retries against platform-sandbox and uses that answer if sandbox knows the hub. Account and upgrade links come from the platform that answered, so sandbox hubs link to marketing-sandbox.
To backfill existing hubs:
node scripts/stamp-hub-platform-origins.mjs # dry run
node scripts/stamp-hub-platform-origins.mjs --write # update worker/wrangler.toml, then commitEach Worker picks up the value on its next deploy.
Check what a hub sees:
curl -sS -H 'Origin: https://<site_id>.lovely-hub.com' https://platform.lovely-home.co.uk/api/public/hub-plan-status | jq '{billingKnown, plan}'
curl -sS -H 'Origin: https://<site_id>.lovely-hub.com' https://platform-sandbox.lovely-home.co.uk/api/public/hub-plan-status | jq '{billingKnown, plan, accountUrl}'Paid signup QA (and when to start fresh)
End-to-end: marketing signup → Stripe test webhook → welcome email → queue → marklovely/lovely-hub-provision workflow Hub provision dispatch (not home-dashboard → Platform site provision). Admin Provision uses the same public orchestrator unless legacy VPS mode is on.
Status:
curl -sS 'https://platform-sandbox.lovely-home.co.uk/api/public/hub-status/<site_id>' | jq .
bash scripts/verify-sandbox-provision-chain.shWebhook 200 but no GitHub run: Stripe only enqueues once; hub-jobs may have failed silently. Break-glass provision:
PLATFORM_RESOURCE_SUFFIX=sandbox node scripts/enqueue-hub-job.mjs \
--queue provision --action provision --site-id <site_id>Watch marklovely/lovely-hub-provision → Hub provision dispatch. Then redeploy platform-sandbox after platform API fixes land on main.
D1 — billing row for a site
Sandbox billing database: lovely-home-platform-billing-sandbox.
SITE_ID=test-sandbox2
wrangler d1 execute lovely-home-platform-billing-sandbox --remote --command \
"SELECT site_id, status, owner_email,
registry_dispatched_at, registry_last_error,
provision_dispatched_at, provision_last_error,
signup_email_sent_at, updated_at
FROM site_billing WHERE site_id = '${SITE_ID}';"If migrations are behind:
PLATFORM_BILLING_D1_NAME=lovely-home-platform-billing-sandbox \
node scripts/apply-platform-billing-migration.mjsMissing queue consumers (NO consumer for lovely-home-hub-jobs-sandbox)
Pages bindings and the hub-jobs Worker can look fine while queue consumers were never created. Common cause: sandbox-hub.tfvars copied manage_hub_queue_consumers = false from production hub.tfvars (used after prod queue import error 11004). Sandbox state is separate — consumers must be true.
Regenerate or edit tfvars:
bashnode scripts/init-sandbox-hub-tfvars.mjs --forceApply platform stack against
platform-sandbox.tfstate(see Step 3).Targeted apply (consumers only, when queues + hub-jobs Worker already exist):
bashterraform apply -var-file=environments/sandbox-hub.tfvars -var=terraform_stack=platform \ -target=module.platform_admin.cloudflare_queue_consumer.hub_provision[0] \ -target=module.platform_admin.cloudflare_queue_consumer.hub_registry[0]Re-verify:
bashbash scripts/verify-sandbox-provision-chain.shRe-enqueue (Stripe will not replay the webhook):
bashPLATFORM_RESOURCE_SUFFIX=sandbox node scripts/enqueue-hub-job.mjs \ --queue provision --action provision --site-id "${SITE_ID}"
Stuck or half-provisioned slug: Prefer a new disposable id (test-sandbox2, …). To remove a test hub end-to-end, see ops-deprovision-stripe-test-hubs.md or platform-provision.md.
Per-hub Terraform sites (test-sandbox2, …)
Customer sandbox hubs live in the customers stack (home-dashboard/customers/{site_id}.tfstate), not in platform-sandbox.tfstate. After provision:
- Hub Worker:
cd worker && npm run deploy:test-sandbox2(ornpx wrangler deploy --env test-sandbox2). - Hub Pages:
unset CLOUDFLARE_API_TOKEN && bash scripts/deploy-cloudflare-pages-site.sh test-sandbox2
See sandbox-ai-hub-creation-qa.md for Workers AI QA on a per-hub env.
Guest / sitter offline House Guide (shipped on main)
After Pages + Worker deploy for the hub under test:
- Schedule a sitter or guest stay (or use an account inside the access window).
- Sign in on the hub → open House Guide → Download for offline on Wi‑Fi. Wait until the banner leaves Checking offline guide status….
- On that sitter device session,
GET /api/sitter-offline/releasereturns 200 and"allowed": true. The same session outside the access window returns 200 and"allowed": false(NO_ACCESS_WINDOW, orSTAY_NOT_MATCHEDwhen the Access email is not on the open stay). An owner session, including View as Guest, returns 403DEVICE_MODE_REQUIRED. Owner preview does not call this URL — use Download for offline (preview). That pack has no lockbox or Wi‑Fi codes. - Enable airplane mode (or block network) → reload → the hub stays in sitter mode, and guide topics and Emergency contacts still open from the saved pack. An email login code here means site data was cleared, not that the download failed.
- During the stay, confirm sit-day Wi‑Fi/lockbox appear when secret sharing allows, then persist offline after a successful online sync.
- Publish a small guide change, go back online, and open House Guide. The banner updates the pack on its own or shows Update offline copy. Download again is available when the copy is ready or expired.
Marketing copy for offline ships from website/ — preview on marketing-sandbox (bash scripts/deploy-sandbox-lovely-home.sh) before production Pages.
Verify
| URL | Purpose |
|---|---|
| https://marketing-sandbox.lovely-home.co.uk/signup | Public signup QA |
| https://platform-sandbox.lovely-home.co.uk | Platform admin |
| https://sandbox.lovely-home.co.uk | Practice hub (prod state — separate) |
PLATFORM_PAGES_PROJECT=home-dashboard-platform-sandbox bash scripts/verify-platform-stripe-env.shScript index: ops-sandbox-scripts.md.