Deployment Guide — Lantern App

Complete guide for deploying the Lantern app to development and production environments using Cloudflare Pages and Firebase.

Overview
Prerequisites
Environment Setup
Local Development
Cloudflare Pages Setup
Firebase Projects Setup
Deployment Workflow
Troubleshooting

Overview

Architecture

Frontend: Vite + React PWA hosted on Cloudflare Pages
Backend: Firebase (Authentication, Firestore, Storage, Functions)
Hosting: Cloudflare Pages with automatic deployments
Documentation: VitePress site deployed to separate subdomain

Note: The documentation site is deployed separately. See DOCS_DEPLOYMENT.md for docs-specific deployment guide.

Environments

Component	Environment	URL	Pages Project	Use Case
App	Production	`ourlantern.app`	`lantern-app`	Live users
App	Development	`dev.ourlantern.app`	`lantern-app-dev`	Team testing
Docs	Production	`docs.ourlantern.app`	`lantern-docs`	Public documentation
Docs	Development	`docs.dev.ourlantern.app`	`lantern-docs-dev`	Unreleased docs
Storybook	Production	`storybook.ourlantern.app`	`lantern-storybook`	Component library
Storybook	Development	`storybook.dev.ourlantern.app`	`lantern-storybook-dev`	Dev component library

Security Headers Configuration

Permissions Policy for Geolocation

IMPORTANT: The public/_headers file includes a Permissions Policy that controls browser feature access.

Permissions-Policy: camera=(), microphone=(), geolocation=(self)

What this does:

camera=() - Blocks camera access (Lantern has no photo features)
microphone=() - Blocks microphone access (not needed)
geolocation=(self) - Allows geolocation for same-origin requests (required for Waves, check-ins, proximity features)

Why geolocation is enabled:

Core features (Waves, Lantern Hub, venue check-ins) require location access
Location is used ephemerally (proximity checks) and NOT retained as history
(self) scope prevents third-party scripts/iframes from accessing location
User must explicitly grant browser permission for each session

Security model:

User clicks "Allow Location" in browser prompt
App gets GPS coordinates from browser
Server validates location (see Location Security in TODO.md)
Location used for feature (proximity match, check-in verification)
Location discarded - NOT stored in database

Testing:

Without geolocation=(self): Browser blocks with "Permissions policy violation"
With geolocation=(self): Browser shows permission prompt, feature works

References:

See docs/TODO.md → "Location Security & Anti-Fraud" for server-side validation requirements
See src/screens/profile/ProfileSettings.jsx for location spoofing debug panel (dev only)

Prerequisites

Required Accounts

[X] Google/Firebase account
[X] Cloudflare account
[X] GitHub account (repo already exists)

Required Tools

bash

# Node.js (v18 or v20)
node --version

# npm (comes with Node)
npm --version

# Git
git --version

# Optional: Cloudflare CLI (wrangler)
npm install -g wrangler

Environment Setup

Step 1: Create Firebase Projects

You need TWO separate Firebase projects:

Development Project

Go to Firebase Console
Click "Add project"
Name: lantern-app-dev
Enable Google Analytics (optional)
Click "Create project"

Production Project

Repeat steps above
Name: lantern-app-prod

Step 2: Get Firebase Configuration

For EACH Firebase project (lantern-app-dev and lantern-app-prod):

Go to Project Settings (gear icon)
Scroll to "Your apps" section
Click "Web" icon (</>) to add a web app
Register app name (e.g., "Lantern Dev" or "Lantern Prod")
Copy the config object that looks like:

javascript

const firebaseConfig = {
  apiKey: "AIzaSy...",
  authDomain: "lantern-app-dev.firebaseapp.com",
  projectId: "lantern-app-dev",
  storageBucket: "lantern-app-dev.appspot.com",
  messagingSenderId: "123456789",
  appId: "1:123456789:web:abcdef"
};

⚠️ IMPORTANT: Keep these configs safe! You'll need them in the next steps.

Step 3: Enable Firebase Services

In EACH Firebase project, enable:

Authentication
- Go to Authentication > Get started
- Enable "Email/Password" provider
- (Later: Add Google, Facebook, etc. as needed)
Firestore Database
- Go to Firestore Database > Create database
- Start in "test mode" (we'll add security rules later)
- Choose a location (e.g., us-central1)
Storage
- Go to Storage > Get started
- Start in "test mode"
Functions (optional for now)
- Will set up when needed

Local Development

Step 1: Clone & Install

bash

# Clone repo (if not already)
git clone https://github.com/cattreedev/lantern_app.git
cd lantern_app

# Install dependencies
npm install

Step 2: Set Up Local Environment

bash

# Copy the example file
cp .env.local.example .env.local

Edit .env.local with your DEV Firebase config:

bash

VITE_FIREBASE_API_KEY=AIzaSy... # from lantern-app-dev
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=123456789
VITE_FIREBASE_APP_ID=1:123456789:web:abcdef
VITE_APP_ENV=local

⚠️ NEVER commit .env.local — it's already in .gitignore

Step 3: Run Development Server

bash

npm run dev

Visit http://localhost:5173 — you should see the app running with dev Firebase!

Step 4: Verify Firebase Connection

Open browser console and look for:

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

Cloudflare Pages Setup

Architecture: Two Separate Projects

We use two independent Cloudflare Pages projects to avoid auth conflicts and keep environments clean:

Project	Branch	Domain	Purpose
`lantern-app`	`main`	`ourlantern.app`	Production (live)
`lantern-app-dev`	`dev`	`dev.ourlantern.app`	Development/staging

Benefits:

No proxy conflicts
Clean separation of environments
Independent environment variables and settings
Easy to manage access policies

Step 1: Create Production Pages Project (`lantern-app`)

Go to Cloudflare Dashboard → Pages
Click "Create a project" → "Connect to Git"
Select cattreedev/lantern_app
Configure:
- Project name: lantern-app
- Production branch: main
- Build command: npm run build
- Build output directory: dist

Step 2: Create Development Pages Project (`lantern-app-dev`)

Click "Create a project" again
Select same repo cattreedev/lantern_app
Configure:
- Project name: lantern-app-dev
- Production branch: dev (not main!)
- Build command: npm run build
- Build output directory: dist

Step 3: Set Environment Variables (Production Project)

In lantern-app project, go to Settings → Environment variables:

Production (main branch):

VITE_FIREBASE_API_KEY = <your-prod-api-key>
VITE_FIREBASE_AUTH_DOMAIN = lantern-app-prod.firebaseapp.com
VITE_FIREBASE_PROJECT_ID = lantern-app-prod
VITE_FIREBASE_STORAGE_BUCKET = lantern-app-prod.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID = <your-prod-sender-id>
VITE_FIREBASE_APP_ID = <your-prod-app-id>
VITE_APP_ENV = production
NODE_VERSION = 20

Step 4: Set Environment Variables (Development Project)

In lantern-app-dev project, go to Settings → Environment variables:

Production (dev branch):

VITE_FIREBASE_API_KEY = <your-dev-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 = <your-dev-sender-id>
VITE_FIREBASE_APP_ID = <your-dev-app-id>
VITE_APP_ENV = development
NODE_VERSION = 20

Step 5: Add Custom Domains

Production Project

In lantern-app, go to Settings → Domains & accounts
Click Add domain
Enter ourlantern.app
Cloudflare auto-creates required DNS records

Development Project

In lantern-app-dev, go to Settings → Domains & accounts
Click Add domain
Enter dev.ourlantern.app
Cloudflare auto-creates required DNS records

Step 6: Verify DNS Configuration

In Cloudflare dashboard, DNS tab should show:

CNAME  ourlantern.app        → lantern-app.pages.dev       (Proxied)
CNAME  dev                   → lantern-app.pages.dev       (Proxied)

Clean up old records (delete if present):

Namecheap parking A record (162.255.119.80)
Parking CNAME (parkingpage.namecheap.com)
Old nameservers (pdns1/pdns2.registrar-servers.com)
Keep or remove MX/SPF based on your email setup

Step 7: Configure Cloudflare Access (Security)

We use three Access applications for defense-in-depth:

1. Production Access App

Go to Cloudflare Zero Trust → Access → Applications
Click Add an application → Self-hosted
Configure:
- Application name: lantern-app
- Subdomain/Domain: ourlantern.app
- Path: /
Click Next and add policy:
- Action: Allow
- Rule name: PIN Authentication
- Session duration: 24 hours
- Include rule: Everyone (or restrict to emails)
- Require: One-time PIN (or email authentication)
Save

2. Development Access App

Click Add an application → Self-hosted
Configure:
- Application name: lantern-app-dev
- Subdomain/Domain: dev.ourlantern.app
- Path: /
Add same policy as production (or customize as needed)

3. Wildcard Access App (Catch-all for future subdomains)

Click Add an application → Self-hosted
Configure:
- Application name: lantern-app-wildcard
- Subdomain/Domain: *.ourlantern.app
- Path: /
Add same PIN policy
This catches any accidental subdomains (e.g., api.ourlantern.app)

Result:

✅ ourlantern.app protected by prod app
✅ dev.ourlantern.app protected by dev app
✅ Any future *.ourlantern.app caught by wildcard app
✅ No conflicts (Cloudflare matches most-specific first)

Firebase Projects Setup

Security Rules (IMPORTANT!)

By default, Firebase is in "test mode" — anyone can read/write. Lock it down:

Firestore Rules

In Firebase Console > Firestore Database > Rules:

javascript

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Default deny
    match /{document=**} {
      allow read, write: if false;
    }
  
    // Users can read/write their own data
    match /users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
  
    // Add more rules as needed
  }
}

Storage Rules

In Firebase Console > Storage > Rules:

javascript

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /{allPaths=**} {
      allow read, write: if request.auth != null;
    }
  }
}

Publish these rules in BOTH projects.

Deployment Workflow

Feature Branch Workflow (Recommended)

bash

# 1. Create feature branch from dev
git checkout -b feature/my-feature dev

# 2. Make changes and test locally
npm run dev
# ... edit code ...

# 3. Commit and push
git add .
git commit -m "Add my feature"
git push origin feature/my-feature

Result: Cloudflare auto-deploys to preview URL:

https://feature-my-feature.lantern-app-dev.pages.dev
Automatically protected by dev Access app (same PIN)
Great for QA and testing

Deploy to Development (`dev.ourlantern.app`)

bash

# Merge feature into dev
git checkout dev
git merge feature/my-feature
git push origin dev

Result: Auto-deploys to https://dev.ourlantern.app

Deploy to Production (`ourlantern.app`)

bash

# Merge dev into main (use PR for code review)
git checkout main
git pull origin main
git merge dev
git push origin main

Result: Auto-deploys to https://ourlantern.app (live)

Branch Strategy

main (production)
  ↑
  └── dev (development/staging)
        ↑
        └── feature/my-feature
        └── fix/bug-fix

Rules:

✅ Work in feature branches
✅ Merge features → dev for testing
✅ Merge dev → main for production releases
❌ Never commit directly to main

Troubleshooting

Build Fails on Cloudflare

Error: Command not found: npm

Fix: Set NODE_VERSION=20 in environment variables

Error: Module not found

Fix: Ensure package-lock.json is committed

Error: Build exceeded time limit

Fix: Check build logs; may need to optimize dependencies

Firebase Not Connecting

Error: Missing Firebase config

Fix: Check environment variables are set in Cloudflare dashboard
Fix: Verify variable names start with VITE_

Error: "Firebase: Error (auth/api-key-not-valid)"

Fix: Double-check API key in Cloudflare environment variables

PWA Not Working

Error: Service worker not registering

Fix: Ensure _headers file is in public/ folder
Fix: Test with npm run build && npm run preview locally

Error: App not installable

Fix: Check manifest at /manifest.webmanifest
Fix: Verify HTTPS (Cloudflare provides this automatically)

Wrong Firebase Project

Error: Seeing dev data in production

Fix: Check Cloudflare environment variables are set correctly for each environment
Fix: Verify VITE_APP_ENV is set to production for main branch

Security Checklist

Before going live:

[ ] Firebase Security Rules are set (NOT test mode)
[ ] Environment variables are set in Cloudflare (not hardcoded)
[ ] .env.local is gitignored (never committed)
[ ] Cloudflare Access is configured (password/PIN protection)
[ ] Firebase Authentication is enabled
[ ] CSP headers are configured in _headers
[ ] HTTPS is enforced (automatic on Cloudflare)

Quick Reference

Useful Commands

bash

# Local development
npm run dev

# Build for production
npm run build

# Preview production build locally
npm run preview

# Run tests
npm test

# Deploy manually with Wrangler (alternative to Git-based)
npx wrangler pages deploy dist

Important Files

.env.local — Local dev config (gitignored)
src/firebase.js — Firebase initialization
public/_headers — Security & PWA headers
public/_redirects — SPA routing config
wrangler.toml — Cloudflare config

Helpful Links

Next Steps

✅ Set up Firebase projects (dev + prod)
✅ Configure Cloudflare Pages
✅ Set environment variables
✅ Create dev branch
✅ Test deployment workflow
🔜 Add Firebase Security Rules
🔜 Set up Cloudflare Access
🔜 Add custom domain (optional)
🔜 Set up Firebase Functions
🔜 Configure CI/CD with GitHub Actions

Questions? Check docs/engineering/ for more details or open an issue!

Deployment Guide — Lantern App ​

Table of Contents ​

Overview ​

Architecture ​

Environments ​

Security Headers Configuration ​

Permissions Policy for Geolocation ​

Prerequisites ​

Required Accounts ​

Required Tools ​

Environment Setup ​

Step 1: Create Firebase Projects ​

Development Project ​

Production Project ​

Step 2: Get Firebase Configuration ​

Step 3: Enable Firebase Services ​

Local Development ​

Step 1: Clone & Install ​

Step 2: Set Up Local Environment ​

Step 3: Run Development Server ​

Step 4: Verify Firebase Connection ​

Cloudflare Pages Setup ​

Architecture: Two Separate Projects ​

Step 1: Create Production Pages Project (lantern-app) ​

Step 2: Create Development Pages Project (lantern-app-dev) ​

Step 3: Set Environment Variables (Production Project) ​

Step 4: Set Environment Variables (Development Project) ​

Step 5: Add Custom Domains ​

Production Project ​

Development Project ​

Step 6: Verify DNS Configuration ​

Step 7: Configure Cloudflare Access (Security) ​

1. Production Access App ​

2. Development Access App ​

3. Wildcard Access App (Catch-all for future subdomains) ​

Firebase Projects Setup ​

Security Rules (IMPORTANT!) ​

Firestore Rules ​

Storage Rules ​

Deployment Workflow ​

Feature Branch Workflow (Recommended) ​

Deploy to Development (dev.ourlantern.app) ​

Deploy to Production (ourlantern.app) ​

Branch Strategy ​

Troubleshooting ​

Build Fails on Cloudflare ​

Firebase Not Connecting ​

PWA Not Working ​

Wrong Firebase Project ​

Security Checklist ​

Quick Reference ​

Useful Commands ​

Important Files ​

Helpful Links ​

Next Steps ​

Deployment Guide — Lantern App

Table of Contents

Overview

Architecture

Environments

Security Headers Configuration

Permissions Policy for Geolocation

Prerequisites

Required Accounts

Required Tools

Environment Setup

Step 1: Create Firebase Projects

Development Project

Production Project

Step 2: Get Firebase Configuration

Step 3: Enable Firebase Services

Local Development

Step 1: Clone & Install

Step 2: Set Up Local Environment

Step 3: Run Development Server

Step 4: Verify Firebase Connection

Cloudflare Pages Setup

Architecture: Two Separate Projects

Step 1: Create Production Pages Project (`lantern-app`)

Step 2: Create Development Pages Project (`lantern-app-dev`)

Step 3: Set Environment Variables (Production Project)

Step 4: Set Environment Variables (Development Project)

Step 5: Add Custom Domains

Production Project

Development Project

Step 6: Verify DNS Configuration

Step 7: Configure Cloudflare Access (Security)

1. Production Access App

2. Development Access App

3. Wildcard Access App (Catch-all for future subdomains)

Firebase Projects Setup

Security Rules (IMPORTANT!)

Firestore Rules

Storage Rules

Deployment Workflow

Feature Branch Workflow (Recommended)

Deploy to Development (`dev.ourlantern.app`)

Deploy to Production (`ourlantern.app`)

Branch Strategy

Troubleshooting

Build Fails on Cloudflare

Firebase Not Connecting

PWA Not Working

Wrong Firebase Project

Security Checklist

Quick Reference

Useful Commands

Important Files

Helpful Links

Next Steps