feat: one-click local deployment with docker compose (#3919)

[Iansabia]

Summary

• Add docker compose up one-click local deployment using real service substitutes (Firebase Emulator Suite, Redis, Typesense, Qdrant) instead of shallow mocks
• Add Qdrant adapter that implements Pinecone's interface so all downstream vector_db code works unchanged
• Minimal changes to 3 existing files (env-var conditionals only, zero behavior change in production)

What's included

New files (10)

File	Purpose
docker-compose.yml	5-service orchestration with health checks
docker/firebase-emulator/Dockerfile	Firebase Emulator Suite (Firestore, Auth, Storage)
docker/firebase-emulator/firebase.json	Emulator port config
docker/firebase-emulator/storage.rules	Permissive local storage rules
backend/.env.docker	Pre-filled env template for local services
backend/database/qdrant_adapter.py	Qdrant adapter implementing Pinecone interface
scripts/init_typesense.py	Idempotent Typesense collection setup
scripts/seed_local.py	Test user creation via Auth emulator
scripts/local_setup.sh	One-click setup wrapper
SELF_HOSTING.md	Quick start guide + architecture diagram

Modified files (3, minimal changes)

File	Change
backend/database/vector_db.py	Qdrant conditional (checks QDRANT_HOST before Pinecone) + None guards on 7 unprotected functions
backend/utils/conversations/search.py	Typesense protocol from env var (1 line, defaults to https)
backend/utils/other/storage.py	Emulator-aware signed URLs with URL encoding (4 lines added)

Service mapping

Production	Local Replacement
Cloud Firestore	Firebase Emulator (FIRESTORE_EMULATOR_HOST)
Firebase Auth	Firebase Emulator (FIREBASE_AUTH_EMULATOR_HOST)
GCS Storage	Firebase Storage Emulator (STORAGE_EMULATOR_HOST)
Redis Cloud	redis:7-alpine (drop-in, same protocol)
Pinecone	qdrant/qdrant (adapter translates API calls)
Typesense Cloud	typesense/typesense:27.1 (HTTP instead of HTTPS)

Test plan

• docker compose up --build — all 5 services start and pass health checks
• curl http://localhost:8080/ — backend responds
• curl http://localhost:4000 — Firebase Emulator UI loads
• python3 scripts/seed_local.py — creates test user, prints token
• curl -H "Authorization: Bearer <token>" http://localhost:8080/v1/users/me — authenticated request works
• Existing unit tests pass with zero regressions (199 passing, 58 pre-existing failures unrelated to changes)

Known limitations

• Pusher: Real-time transcription not included (Phase 2)
• Modal.com: Decorators are no-ops via uvicorn — serverless functions won't execute
• OpenAI API key required: Documented in template; backend starts fine without it but LLM features won't work

Closes #3919

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive local development environment using Docker Compose, which is a great addition for simplifying setup. The changes include adding service definitions, a Qdrant adapter to replace Pinecone locally, and necessary modifications to the backend code to support the emulated services. My review focuses on improving the robustness of the setup process. I've identified a couple of high-severity issues related to service health checking in the setup script which could lead to race conditions and setup failures. The proposed changes will make the local startup process more reliable.