Lantern

Appearance

Initial Project Setup — Historical Reference ​

⚠️ Archived. Not forward-looking.

This document captures how the Lantern infrastructure was originally provisioned: the two Firebase projects, Cloudflare Pages, and the branch-based deployment strategy. None of these steps need to be repeated for new developers — those projects already exist.

Kept for:

  • Institutional knowledge ("why was it set up this way?")
  • Disaster recovery (rebuilding from scratch if the GCP org is lost)
  • Partners / forks ("Lantern for cities" or similar deployments)
  • Audit / compliance reference

For day-to-day new-developer onboarding, see ENVIRONMENT_SETUP.md.

Last verified accurate: content matches the state of the lantern-app-dev / lantern-app-prod projects and Cloudflare Pages setup circa Q1 2026. May drift over time; treat as a starting point, not a guaranteed-current procedure.

What this document covers ​

The original ~20-min bootstrapping procedure for a fresh Lantern deployment:

  1. Create two Firebase projects (dev + prod)
  2. Enable Firebase services (Auth, Firestore, Storage) in each
  3. Wire Cloudflare Pages to the GitHub repo
  4. Configure environment variables for both Production (main) and Preview (dev + feature branches)
  5. Set up the main / dev branch strategy

These steps assume you have:

  • A GitHub account that owns (or has admin on) the repository
  • A GCP / Firebase account
  • A Cloudflare account with a verified domain

Step 1: Create Firebase DEV Project ​

  1. Go to https://console.firebase.google.com
  2. Click "Add project"
  3. Name: lantern-app-dev
  4. Disable Google Analytics (or enable if you want)
  5. Click "Create project"

Wait for project to be created (~1 minute).

Step 2: Enable Firebase Services in DEV ​

In your lantern-app-dev project:

Authentication:

  1. Click "Authentication" in left sidebar
  2. Click "Get started"
  3. Click "Email/Password"
  4. Enable the toggle
  5. Click "Save"

Firestore Database:

  1. Click "Firestore Database"
  2. Click "Create database"
  3. Choose "Start in test mode"
  4. Select region (e.g., us-central1)
  5. Click "Enable"

Storage:

  1. Click "Storage"
  2. Click "Get started"
  3. Start in test mode
  4. Click "Next" → "Done"

Step 3: Create Firebase PRODUCTION Project ​

Repeat Steps 1–2 but name the project lantern-app-prod:

  1. Firebase Console → Add project
  2. Name: lantern-app-prod
  3. Enable Authentication, Firestore, Storage (same as dev)
  4. Get the config (⚙️ → Project settings → Add web app → "Lantern Prod")

⚠️ Save both configs (dev AND prod) — you'll need them for Cloudflare.

Step 4: Set Up Cloudflare Pages ​

Prerequisites: Have your GitHub repo cattreedev/lantern_app ready.

4.1: Create Cloudflare Pages Project ​

  1. Go to https://dash.cloudflare.com
  2. Click "Pages" in left sidebar
  3. Click "Create a project"
  4. Click "Connect to Git"
  5. Authorize GitHub (if needed)
  6. Select repository: cattreedev/lantern_app
  7. Click "Begin setup"

4.2: Configure Build Settings ​

  • Project name: lantern-app
  • Production branch: main
  • Build command: npm run build
  • Build output directory: dist
  • Root directory: (leave empty or /)

Click "Save and Deploy" (it will fail first time — that's OK!)

4.3: Set Environment Variables ​

  1. Go to your Cloudflare Pages project
  2. Click "Settings" → "Environment variables"

For Production (main branch):

Click "Add variable" for each of these (using your lantern-app-prod config):

Variable NameValue (from lantern-app-prod)
VITE_FIREBASE_API_KEYAIzaSy... (prod)
VITE_FIREBASE_AUTH_DOMAINlantern-app-prod.firebaseapp.com
VITE_FIREBASE_PROJECT_IDlantern-app-prod
VITE_FIREBASE_STORAGE_BUCKETlantern-app-prod.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID123... (prod)
VITE_FIREBASE_APP_ID1:123... (prod)
VITE_APP_ENVproduction
NODE_VERSION20

For Preview (all other branches):

Repeat above, but use values from lantern-app-dev config:

Variable NameValue (from lantern-app-dev)
VITE_FIREBASE_API_KEYAIzaSy... (dev)
VITE_FIREBASE_AUTH_DOMAINlantern-app-dev.firebaseapp.com
VITE_FIREBASE_PROJECT_IDlantern-app-dev
VITE_FIREBASE_STORAGE_BUCKETlantern-app-dev.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID123... (dev)
VITE_FIREBASE_APP_ID1:123... (dev)
VITE_APP_ENVdevelopment
NODE_VERSION20

Click "Save"

Step 5: Trigger First Deployment ​

In your terminal:

bash
# Make a small change to trigger deployment
echo "# Deployment test" >> README.md

# Commit and push
git add .
git commit -m "Configure deployment environment"
git push origin main

Wait ~2 minutes for build.

Go to Cloudflare Pages → "Deployments" to watch progress.

✅ Success! When build completes, visit your production URL.

Step 6: Create Dev Branch ​

bash
# Create dev branch from main
git checkout -b dev
git push origin dev

In Cloudflare Pages:

  1. Go to Settings → Builds & deployments
  2. Verify "Preview deployments" is enabled for all branches

Now when you push to dev, it auto-deploys to a preview URL.

Why this structure? ​

DecisionRationale
Two Firebase projects (lantern-app-dev + lantern-app-prod)Hard isolation — bad data, mistaken deletes, schema experiments in dev can never affect prod.
Branch → environment mapping (main → prod, dev → preview)Auto-deployment without manual gates; promotes via PR merges.
GCP Secret Manager (not Cloudflare Pages env vars)Single source of truth for server-side secrets — Cloud Functions, Cloud Run, and local dev all read the same values. Cloudflare Pages env vars are reserved for VITE_* public values that need to be in the browser bundle.
us-central1 regionMatches the rest of the GCP infrastructure (Cloud Run, Dataform, etc.).
Test-mode Firestore initiallyFaster setup; security rules are layered on later via firestore.rules in the repo.

What's been added since ​

Since the initial setup, the project has grown additional infrastructure that also requires provisioning if you're rebuilding from scratch. These are documented in their own files:

  • Cloud Functions — Firebase Functions v2 with secrets via defineSecret. See SECRETS_MANAGEMENT.md.
  • Cloud Run services — Auth, Venue, Analytics, Merchants, Assistant, Docs, Lanterns. Each has its own deploy workflow in .github/workflows/deploy-dev.yml.
  • Dataform — BigQuery transforms. See project_dataform_flat_branch memory note.
  • Cloud Run Jobs — ingest-cloudflare, ingest-github, ingest-invoices for the billing pipeline. See project_billing_pipeline_state.
  • Workload Identity Federation (WIF) — for keyless CI auth. Configured in GCP IAM, referenced in deploy-*.yml workflows.

The canonical "how does this all wire together" reference is the deploy workflow files themselves — they show every service, every secret, every IAM grant in executable form.

Built with VitePress

Copyright © 2026 Lantern