Environment Setup — New Developer Onboarding

Time to complete: ~5 minutes (once a maintainer has granted you GCP access)

This guide gets a new developer from git clone to a running local dev server.

For maintainers / forkers: the original Firebase project creation, Cloudflare Pages provisioning, and prod-deploy wiring lives in INITIAL_PROJECT_SETUP.md. Those steps are done; you should not need to repeat them.

Prerequisites

Before you start, you need:

Node.js v20+ and npm v8+ (node --version, npm --version)
Git configured with your work email + 2FA on your GitHub account
GCP access to lantern-app-dev with roles/secretmanager.secretAccessor (a maintainer grants this — see Granting access below)
Firebase access to lantern-app-dev (auto-included if you're in the GCP project)
gcloud CLI installed — https://cloud.google.com/sdk/docs/install
firebase CLI installed — npm install -g firebase-tools

Setup

bash

# 1. Clone + install workspace dependencies
git clone git@github.com:cattreedev/lantern_app.git
cd lantern_app
npm install

# 2. One-time authentication (uses your Google account — no key files)
gcloud auth application-default login
firebase login

# 3. Populate .env.local
npm run env:bootstrap

# 4. Run the app
npm run dev

Open http://localhost:5173. Browser console should print:

🔥 Firebase initialized (local environment)
Project: lantern-app-dev

If you see that, you're connected correctly.

What `npm run env:bootstrap` does

The script (tooling/scripts/bootstrap-env.mjs):

Creates .env.local from .env.local.example if it doesn't exist yet
Fetches 18 server-side secrets from GCP Secret Manager (Cloudflare/Resend/Anthropic/Discord/etc.)
Fetches 7 public Firebase config values via firebase apps:sdkconfig WEB (the VITE_FIREBASE_* keys)
Merges everything into .env.local, preserving existing values

You don't need to copy anything from the Firebase Console manually — the bootstrap handles it.

What you still set by hand

Three per-developer values can't be shared from Secret Manager:

Variable	What it is	How to get it
`GH_PAT`	Your personal GitHub PAT (`repo` scope)	https://github.com/settings/tokens
`GITHUB_OWNER`	Your GitHub username	Your username (e.g. `mechelle`)
`GOOGLE_APPLICATION_CREDENTIALS`	Path to ADC key file	Usually leave unset — `gcloud auth application-default login` handles it

Open .env.local after running bootstrap to fill GH_PAT and GITHUB_OWNER. The remaining 25 values are already populated.

Re-running bootstrap

Command	When to use
`npm run env:bootstrap`	First-time setup, or after a new secret is added to `SECRET_MAP`
`npm run env:bootstrap:dry-run`	Preview what would be written without modifying `.env.local`
`npm run env:bootstrap:force`	After a secret is rotated — overwrite existing values

See Secrets Management for the full deep dive.

Granting access (maintainer task)

Before a new dev can run npm run env:bootstrap, grant their Google account the Secret Manager accessor role:

bash

gcloud projects add-iam-policy-binding lantern-app-dev \
  --member="user:newdev@example.com" \
  --role="roles/secretmanager.secretAccessor"

Firebase access is automatically included for any user with project-level access (no additional step needed for firebase apps:sdkconfig).

Manual fallback

If gcloud or firebase-tools aren't installable in your environment (unusual — they work on every modern OS), open .env.local.example and copy values from the Firebase Console / a teammate. The bootstrap script prints remediation commands for each failure mode (missing CLI, expired auth, no access).

The minimum vars needed to start the web app:

bash

VITE_FIREBASE_API_KEY=...
VITE_FIREBASE_AUTH_DOMAIN=lantern-app-dev.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=lantern-app-dev
VITE_FIREBASE_STORAGE_BUCKET=lantern-app-dev.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=...
VITE_FIREBASE_APP_ID=...
VITE_APP_ENV=local

Copy the values from Firebase Console → Project Settings → Your apps → Lantern Dev.

Optional: Location Spoofing for Development

Lantern's core features (check-ins, nearby users, venue offers) depend on geolocation. To test without physically visiting venues, spoof your location in dev.

Option 1: Environment variable (auto-loads on startup)

bash

# .env.local
VITE_DEV_TEST_LOCATION="40.7128,-74.0060"

Get coordinates from Google Maps: right-click any location → click the coordinates that appear → paste into .env.local. Restart npm run dev for changes to apply.

Option 2: Debug panel (change on the fly)

While running npm run dev:

Go to Profile Settings (#/profile)
Click the "Privacy" tab
Scroll to the purple "🚧 Dev: Location Spoofing" panel
Enter lat/lng → click "Set Location"

The spoofed location persists in localStorage until you clear it.

⚠️ Location spoofing is only available in development builds. Production builds use real geolocation regardless of these settings.

Environment detection in code

When adding dev-only features (debug panels, simulate buttons, dev-only API calls), use hostname-based detection rather than import.meta.env.DEV:

javascript

const hostname = typeof window !== 'undefined' ? window.location.hostname : ''
const isProductionEnv = import.meta.env.VITE_APP_ENV === 'production' || hostname === 'ourlantern.app'
const isDev = !isProductionEnv

Why hostname check?

import.meta.env.DEV only works on localhost (Vite dev server)
Deployed dev sites (dev.ourlantern.app) need hostname detection
Production site (ourlantern.app) should hide all dev features

Examples in codebase:

apps/web/src/screens/dashboard/Dashboard.jsx — "Simulate Wave" button
apps/web/src/screens/profile/ProfileSettings.jsx — Location spoof panel
apps/web/src/firebase.js — Firebase environment logging

Common issues

Symptom	Fix
`npm run env:bootstrap` reports `permission` for every secret	Maintainer hasn't granted you `roles/secretmanager.secretAccessor` yet — see Granting access
`npm run env:bootstrap` reports `auth`	Run `gcloud auth application-default login` again — ADC expired
Bootstrap reports `no-cli` for Firebase fetch	`npm install -g firebase-tools` then re-run
"Firebase not initialized" in browser console	`.env.local` is missing `VITE_FIREBASE_*` values — re-run bootstrap
Wrong Firebase project connecting	`VITE_FIREBASE_PROJECT_ID` is wrong in `.env.local` — should be `lantern-app-dev` for local dev

What's next

Developer Onboarding — broader context (architecture, code conventions, where to find things)
Secrets Management — deep dive on the secret/env system
AGENTS.md — project rules and commands

For deploying / Cloudflare Pages / prod Firebase projects → INITIAL_PROJECT_SETUP.md (historical reference, not forward-looking).

Environment Setup — New Developer Onboarding ​

Prerequisites ​

Setup ​

What npm run env:bootstrap does ​

What you still set by hand ​

Re-running bootstrap ​

Granting access (maintainer task) ​

Manual fallback ​

Optional: Location Spoofing for Development ​

Option 1: Environment variable (auto-loads on startup) ​

Option 2: Debug panel (change on the fly) ​

Environment detection in code ​

Common issues ​

What's next ​

Environment Setup — New Developer Onboarding

Prerequisites

Setup

What `npm run env:bootstrap` does

What you still set by hand

Re-running bootstrap

Granting access (maintainer task)

Manual fallback

Optional: Location Spoofing for Development

Option 1: Environment variable (auto-loads on startup)

Option 2: Debug panel (change on the fly)

Environment detection in code

Common issues

What's next