Skip to content

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:

bash
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", and sites = {}.
  • 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.example or sandbox-hub.tfvars.example (replace YOUR_* before apply).

Re-run after hub.tfvars changes:

bash
node scripts/init-sandbox-hub-tfvars.mjs --force

Manual: 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) ​

bash
cp terraform/environments/backend.hcl.example terraform/environments/backend.hcl

In 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).

hcl
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):

bash
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_KEY

Step 3 — Terraform init / apply ​

bash
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=platform

Apply errors (common) ​

ErrorFix
20217 exceeded maximum number of zone rulesets for phase http_ratelimitSet 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 AccessCreate 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:

bash
gh secret list --repo marklovely/home-dashboard | rg CLOUDFLARE_API_TOKEN
# Must be set: CLOUDFLARE_API_TOKEN

Terraform apply is local — it uses sandbox-hub.tfvars + shell env, not GitHub Actions secrets.

Local applySource
CLOUDFLARE_API_TOKENYour shell (same token class as GitHub CLOUDFLARE_API_TOKEN)
R2 stateAWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (or GitHub TF_STATE_R2_*)
Stripe / Turnstile / Resend / platform tokenssandbox-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.

SourceWhen marketing-sandbox updates
Push to sandbox branchCI workflow Deploy sandbox on push (.github/workflows/deploy-sandbox-on-push.yml)
Manual Deploy sandbox Lovely HomeOnly when someone runs the workflow (see below)
Feature branchesNever 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 targetWhat 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:

VariableDefaultPurpose
SANDBOX_MARKETING_PAGES_PRODUCTION_BRANCHmainBranch 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:

bash
SANDBOX_MARKETING_PAGES_PRODUCTION_BRANCH=main LOVELY_STACK=sandbox bash scripts/deploy-sandbox-lovely-home.sh

Ways to preview marketing from a feature branch (e.g. PR #697 feature/marketing-offline-guest-help):

  1. Local deploy (recommended for quick iteration) — check out the branch, then deploy (OAuth; unset API token):

    bash
    git checkout feature/marketing-offline-guest-help
    unset CLOUDFLARE_API_TOKEN
    bash scripts/deploy-sandbox-lovely-home.sh
  2. GitHub Actions manual deploy — Actions → Deploy sandbox Lovely Home → confirm deploy-sandbox → set git_ref to your branch (default is main, which does not match an open PR). Example: feature/marketing-offline-guest-help.

  3. 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.

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):

bash
git rev-parse HEAD
cat website/version.json
curl -sS https://marketing-sandbox.lovely-home.co.uk/version.json
CheckExpected
website/version.jsonSame as root package.json (e.g. 3.6.0 on current main)
Live curl …/version.jsonMatches your deploy commit after Wrangler finishes
Git branchAt 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:

bash
npm run stage-marketing-sandbox
cat dist-marketing-sandbox/version.json

After bash scripts/deploy-sandbox-lovely-home.sh, confirm:

bash
curl -sS https://marketing-sandbox.lovely-home.co.uk/version.json

Local (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.

bash
unset CLOUDFLARE_API_TOKEN
bash scripts/deploy-sandbox-lovely-home.sh

GitHub Actions: workflow Deploy sandbox Lovely Home → confirm with deploy-sandbox → optional git_ref (branch/SHA to checkout before deploy; default main).

Then:

bash
PLATFORM_BILLING_D1_NAME=lovely-home-platform-billing-sandbox \
  node scripts/apply-platform-billing-migration.mjs

Platform 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 (fetchHubPlatform in worker/src/lib/hubPlanLimits.js).
  • The Worker keeps a confirmed hub-plan-status answer 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 and billingKnown: false answers 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_ORIGIN in the provision environment. HUB_PLATFORM_API_ORIGIN_DETECT=0 skips 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:

bash
node scripts/stamp-hub-platform-origins.mjs            # dry run
node scripts/stamp-hub-platform-origins.mjs --write    # update worker/wrangler.toml, then commit

Each Worker picks up the value on its next deploy.

Check what a hub sees:

bash
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}'

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:

bash
curl -sS 'https://platform-sandbox.lovely-home.co.uk/api/public/hub-status/<site_id>' | jq .
bash scripts/verify-sandbox-provision-chain.sh

Webhook 200 but no GitHub run: Stripe only enqueues once; hub-jobs may have failed silently. Break-glass provision:

bash
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.

bash
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:

bash
PLATFORM_BILLING_D1_NAME=lovely-home-platform-billing-sandbox \
  node scripts/apply-platform-billing-migration.mjs

Missing 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.

  1. Regenerate or edit tfvars:

    bash
    node scripts/init-sandbox-hub-tfvars.mjs --force
  2. Apply platform stack against platform-sandbox.tfstate (see Step 3).

    Targeted apply (consumers only, when queues + hub-jobs Worker already exist):

    bash
    terraform 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]
  3. Re-verify:

    bash
    bash scripts/verify-sandbox-provision-chain.sh
  4. Re-enqueue (Stripe will not replay the webhook):

    bash
    PLATFORM_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 (or npx 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:

  1. Schedule a sitter or guest stay (or use an account inside the access window).
  2. Sign in on the hub → open House Guide → Download for offline on Wi‑Fi. Wait until the banner leaves Checking offline guide status….
  3. On that sitter device session, GET /api/sitter-offline/release returns 200 and "allowed": true. The same session outside the access window returns 200 and "allowed": false (NO_ACCESS_WINDOW, or STAY_NOT_MATCHED when the Access email is not on the open stay). An owner session, including View as Guest, returns 403 DEVICE_MODE_REQUIRED. Owner preview does not call this URL — use Download for offline (preview). That pack has no lockbox or Wi‑Fi codes.
  4. 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.
  5. During the stay, confirm sit-day Wi‑Fi/lockbox appear when secret sharing allows, then persist offline after a successful online sync.
  6. 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 ​

URLPurpose
https://marketing-sandbox.lovely-home.co.uk/signupPublic signup QA
https://platform-sandbox.lovely-home.co.ukPlatform admin
https://sandbox.lovely-home.co.ukPractice hub (prod state — separate)
bash
PLATFORM_PAGES_PROJECT=home-dashboard-platform-sandbox bash scripts/verify-platform-stripe-env.sh

Script index: ops-sandbox-scripts.md.