Local dev origin defaults

• Issue: #1002: fix(dev-env): local dev proxies venues and analytics to Cloud Run, so branch backend changes are invisible locally
• Started: 2026-08-30
• Branch: feat/admin-and-merchant-portals

What is this project for?

Making local dev talk to local services by default, so a backend change on a branch is visible without merging and deploying.

What is the decision behind it?

DECIDED by the operator, 2026-08-30, verbatim: "by default we should be using localhost."

She reached it after asking why the System Health uptime tab showed 4 endpoints when the branch code monitors 9, and correctly rejecting the first answer, which framed her .env.local as the thing to patch. Her file matches .env.local.example exactly. The example is the defect.

What is actually broken?

Four of six origins point at localhost, two point at Cloud Run, and a comment claims all six are Cloud Run.

• VENUE_API_ORIGIN and ANALYTICS_API_ORIGIN are the two stragglers.
• Nothing in the repo documents why, and no doc mentions the split at all.

The consequence is that two services cannot be reviewed locally.

• The admin portal proxies /api/analytics to ANALYTICS_API_ORIGIN, resolved by Vite at boot. It asks the deployed service and never the local one, even when the local one is running and healthy.
• Every other service is visible locally. These two are not.

It has cost three investigations on three days.

• 2026-08-27, 2026-08-28, 2026-08-30. Twice the given answer was "restart your local analytics-api", which cannot work.
• 921c718c wrote the true cause into its own commit message on 2026-08-27 and it still recurred twice after that, which is why the fix has to be the default rather than a note.

What needs to change?

File	Change	Tracked
.env.local.example	Both origins to localhost ( venues 8080, analytics 8082 ), and fix the block comment	yes
docs/engineering/testing/runs/analytics-config-and-reports/README.md	Quotes the old values, same edit	yes
The operator's .env.local	Same two lines	no, untracked, takes effect on admin server restart

What is the real work?

The verification, not the two lines.

• Both local services answer /health, but healthy is not the same as holding every permission the deployed service has. Analytics reads BigQuery.
• If a surface degrades after the flip, that is very likely why those two were left remote. Write that reason into the example rather than reverting silently, or the folklore survives a fourth time.

What did the verification show?

Verified 2026-08-30 on my own admin portal at http://localhost:3013 (mine, this branch, pointed at the already running local venues-api on 8080 and analytics-api on 8082). The operator's stack on 3001 and 8080 to 8086 was left running and untouched. Full record in run-log.md.

The flip works, and the endpoint count is the proof.

• System Health uptime shows 9 endpoints, all healthy, against the local analytics-api. Restarting the same portal against the deployed one gives 4. Same session, same browser, only the origin changed.

One panel degrades locally, and the reason is a missing IAM role, not a broken idea.

• System Health > Errors > Server Errors reads Cloud Logging, which answers 403 for the local service account (firebase-adminsdk-fbsvc@lantern-app-dev) because it lacks roles/logging.viewer. The service degrades to a message naming that role, exactly as getServerErrorsMetrics is written to.
• This is not why the two origins were left remote. Everything else that could plausibly have justified it works locally: BigQuery table metadata, a real Query Console job, and the Venue Activity rankings all returned live data. So the flip stands, and the gap is written into .env.local.example beside the two lines rather than reverted.
• Open: whether the DEPLOYED runtime service account holds roles/logging.viewer. gcloud was not available in the verifying session, so the IAM check is unrun.

Two things came out of the run that the plan did not anticipate.

• Her .env.local was NOT edited. Vite watches the env files and RESTARTS the dev server when one changes, so the edit is not inert: it would have restarted her portal mid-review. The two lines are hers to apply when she wants them.
• DOCS_API_ORIGIN is missing from both .env.local and .env.local.example even though apps/admin/vite.config.mjs proxies it. Out of scope for #1002, worth a follow-up.

Where does the evidence live?

• Browser captures: screens/ in this folder.
• Run record: run-log.md in this folder.
• Playwright harness: harness/ in this folder.