Skip to content

Platform admin Terraform — pre-apply checklist ​

Use this before every Platform admin Terraform apply that updates home-dashboard-platform Pages env (GitHub Actions Platform admin Terraform, local terraform apply -target=module.platform_admin[0], or full platform stack apply).

Related: Platform admin · Grafana dashboards · Account plans & Stripe · hub.tfvars.example

Why this exists ​

Platform admin Terraform replaces the entire home-dashboard-platform Pages production env_vars map. Any value missing from the input Terraform sees is removed from Cloudflare — including keys you only set in the dashboard.

Repeat incidents:

  • Grafana Workers AI / Cloudflare billing panels empty — PLATFORM_CF_API_TOKEN missing from the apply input.
  • Grafana OpenAI panels NOT_CONFIGURED — PLATFORM_OPENAI_ADMIN_KEY missing while fixing unrelated Stripe vars.
  • Grafana GitHub Actions usage configured: false — platform_github_billing_token missing from hub.tfvars on a local apply (or the GitHub secret missing on a workflow apply).
  • Stripe checkout 503 — STRIPE_* missing during apply.

Two apply paths (do not mix them up) ​

PathWhat Terraform readsWhere secrets must exist
GitHub Actions — workflow Platform admin Terraformgenerate-hub-tfvars.mjs → hub.generated.tfvars built from GitHub Actions secrets on the runnerRepo Settings → Secrets and variables → Actions. Local hub.tfvars is not used.
Local laptop — terraform apply -var-file=environments/hub.tfvarsYour local terraform/environments/hub.tfvars (and optional hub.generated.secrets.tfvars.json)Same values as GitHub must be uncommented and pasted into hub.tfvars. Secrets only in GitHub are invisible to local apply → Terraform drops those Pages keys.

There is no automatic GitHub → hub.tfvars sync script. For local apply:

  1. Open GitHub secret in the browser (or gh secret list — values are not readable via CLI).
  2. Copy each value into the matching commented line in hub.tfvars.example (master GitHub secret → hub.tfvars variable section).
  3. Save as terraform/environments/hub.tfvars (gitignored — never commit).

After editing locally, push secrets back to GitHub when needed:

bash
node scripts/sync-hub-tfvars-to-github-secrets.mjs --repo marklovely/home-dashboard --profile provision

1. GitHub Actions secrets (repo: home-dashboard) ​

Confirm these are non-empty before dispatching Platform admin Terraform (the workflow blocks apply if Grafana secrets are empty; Stripe rows can still wipe if unset):

Secrethub.tfvars key (local apply)Pages env
PLATFORM_CF_API_TOKENplatform_cf_api_tokenPLATFORM_CF_API_TOKEN
PLATFORM_OPENAI_ADMIN_KEYplatform_openai_admin_keyPLATFORM_OPENAI_ADMIN_KEY
PLATFORM_GITHUB_BILLING_TOKEN (or legacy GH_BILLING_TOKEN)platform_github_billing_tokenPLATFORM_GITHUB_BILLING_TOKEN
STRIPE_SECRET_KEYstripe_secret_keySTRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRETstripe_webhook_secretSTRIPE_WEBHOOK_SECRET
STRIPE_PRICE_IDstripe_price_idSTRIPE_PRICE_ID
STRIPE_PRICE_ID_YEARLYstripe_price_id_yearlySTRIPE_PRICE_ID_YEARLY
STRIPE_PRICE_ID_FREEstripe_price_id_freeSTRIPE_PRICE_ID_FREE
MARKETING_MAINTENANCE_MODE (true / 1)marketing_maintenance_modeMARKETING_MAINTENANCE_MODE
MAINTENANCE_BYPASS_SECRETmaintenance_bypass_secretMAINTENANCE_BYPASS_SECRET

Full mapping (Turnstile, Resend, account Stripe prices, archive secret, etc.): hub.tfvars.example.

Marketing maintenance: Prefer Platform settings → Maintenance on platform.lovely-home.co.uk (persists in D1). Terraform/CI vars above keep Pages env in sync when you need env-based enablement or a bypass secret; a missing marketing_maintenance_mode line on apply does not turn off maintenance that was enabled via the dashboard (D1 wins once set).

Account plan prices (optional until checkout ships): STRIPE_ACCOUNT_PRICE_* ↔ stripe_account_price_* — see Account plans §2.

2. Local apply parity check ​

Before terraform apply on a laptop:

  • [ ] platform_cf_api_token and platform_openai_admin_key are set in hub.tfvars (not only in GitHub).
  • [ ] Stripe block matches GitHub secrets you rely on in production.
  • [ ] export CLOUDFLARE_API_TOKEN=... for Terraform API (often same token as platform_cf_api_token, but stored separately).

generate-hub-tfvars.mjs logs warnings when Grafana env vars are empty. Local apply is not blocked — CI is blocked for empty Grafana secrets.

3. Verify scripts (after apply) ​

From a machine with API access:

bash
bash scripts/verify-platform-ai-usage-pages-env.sh   # Grafana AI usage Pages env (token + provider keys)
bash scripts/verify-grafana-platform-api.sh          # Infinity auth + live GET /api/platform/ai-usage
bash scripts/verify-platform-stripe-env.sh           # Hub signup Stripe + account price slots
bash scripts/verify-platform-billing-env.sh          # Billable usage API token scopes

Fix missing slots in the path you used (GitHub secrets or hub.tfvars), then re-apply — do not rely on manual Pages dashboard edits (next apply overwrites them).

4. Grafana-specific ​

  • Infinity headers (Access service token) are separate from Pages env — see Grafana dashboards.
  • After apply, spot-check Lovely Home — AI usage and Cloudflare Billing dashboards; empty Workers AI almost always means PLATFORM_CF_API_TOKEN dropped.

5. When dashboards can wait ​

If you intentionally omit Grafana secrets for a one-off Access/DNS change, do not run Platform admin Terraform against Pages env — use a narrower target or restore secrets first. Skipping Grafana secrets guarantees panel regression on the next full platform apply.