Skip to content

quick-start-emulators.md

Latest commit

 

History

History
123 lines (79 loc) · 2.74 KB

quick-start-emulators.md

File metadata and controls

123 lines (79 loc) · 2.74 KB

Quick Start with Firebase Emulators

Run oboapp locally with zero cloud dependencies using Firebase Emulators and mock APIs.

Prerequisites

  • Docker and Docker Compose
  • Node.js 20+

Setup (5 minutes)

1. Configure Environment

# Copy environment templates
cp ingest/.env.example.emulator ingest/.env.local
cp web/.env.example.emulator web/.env.local

2. Install Dependencies

pnpm install

Note: run dependency installation the root folder of the monorepo

3. Start Emulators

3.1. via Docker

docker-compose up firebase-emulators

Wait for: ✔ All emulators ready! It is now safe to connect your app.

3.2. without using Docker

cd ingest
pnpm emulators

Wait for: ✔ All emulators ready! It is now safe to connect your app. Emulator UI: http://localhost:4000

4. Seed Test Data (First Time)

Open new terminal:

cd ingest
pnpm emulator:seed

Seeded messages are intentionally labeled as test data so they are clearly fake if they are viewed outside the emulator workflow.

Stop emulators (Ctrl+C), then restart. Data persists across restarts.

5. Start Web App

cd web
pnpm dev

Make sure to add your Google Maps API key to the NEXT_PUBLIC_GOOGLE_MAPS_API_KEY variable in web/.env.local.

App: http://localhost:3000

What You Get

  • Firestore database with sample messages, sources, interest zones
  • Firebase Authentication (Google Sign-In mocked)
  • Mock external APIs (Gemini, Google Geocoding, Overpass, Cadastre)
  • Emulator UI for data inspection

Common Operations

Run crawler (mocked):

cd ingest
pnpm crawl --source rayon-oborishte-bg --dry-run

Run ingestion pipeline (mocked):

cd ingest
pnpm ingest

Reset data:

cd ingest
pnpm emulator:clear
pnpm emulator:seed

Run the reseed commands after pulling changes to the seed fixtures so existing local emulator data picks up the latest warning text.

Troubleshooting

Emulators won't start: Install firebase-tools globally: pnpm add -g firebase-tools

Web app can't connect: Verify NEXT_PUBLIC_USE_FIREBASE_EMULATORS=true in web/.env.local

Empty Firestore UI: Navigate to http://localhost:4000/firestore/default/data?ns=demo-project

Mock APIs not working: Verify MOCK_*=true variables in ingest/.env.local

Known Limitations

  • Firebase Cloud Messaging has no emulator
  • Firestore indexes are ignored
  • All external API calls are mocked

For production setup, see production-setup.md.

For mock customization, see external-api-mocks.md.