Merge pull request #18 from YuWei-CH/deployment

Deployment mode

Author: YuWei-CH

.env.example

@@ -38,3 +38,21 @@ OPENROUTER_MODEL="z-ai/glm-4.5-air:free"
 
 # Optional: Database URL (default is an auto-created SQLite DB under backend/)
 # DATABASE_URL="sqlite+pysqlite:////absolute/path/to/easyrelocate.db"
+
+# Optional: keep both local + cloud DB URLs, and select via EASYRELOCATE_DB.
+# EASYRELOCATE_DB="local"   # local|cloud (default: local)
+# DATABASE_URL_LOCAL="sqlite+pysqlite:////absolute/path/to/easyrelocate.db"
+# DATABASE_URL_CLOUD="postgresql+psycopg://DB_USER:DB_PASSWORD@/DB_NAME?host=/cloudsql/INSTANCE_CONNECTION_NAME"
+
+# Optional: CORS allowlist for browsers (comma-separated).
+# In production, set this to your Vercel domain(s).
+# CORS_ALLOW_ORIGINS="https://your-vercel-app.vercel.app,https://easyrelocate.yourdomain.com"
+
+# Optional: Allow anonymous users to get a 30-day workspace token from the web UI.
+# Production note: enable only if you also add protection (rate limiting / bot protection).
+# ENABLE_PUBLIC_WORKSPACE_ISSUE="1"
+# PUBLIC_WORKSPACE_TTL_DAYS="30"
+
+# Optional: Postgres (Cloud SQL / Cloud Run examples)
+# DATABASE_URL="postgresql+psycopg://DB_USER:DB_PASSWORD@/DB_NAME?host=/cloudsql/INSTANCE_CONNECTION_NAME"
+# DATABASE_URL="postgresql+psycopg://DB_USER:DB_PASSWORD@DB_HOST:5432/DB_NAME"

.env.server.example

@@ -0,0 +1,41 @@
+# EasyRelocate — server (Option B: self-hosted backend + Postgres + Caddy)
+#
+# Copy to `.env.server` on your server and fill in values:
+#   cp .env.server.example .env.server
+#
+# Then deploy:
+#   docker compose -f docker-compose.server.yml --env-file .env.server up -d --build
+#
+# Never commit `.env.server` (it contains secrets).
+
+###############################################################################
+# Postgres (Docker)
+###############################################################################
+POSTGRES_DB="easyrelocate"
+POSTGRES_USER="easyrelocate"
+POSTGRES_PASSWORD="CHANGE_ME_STRONG_PASSWORD"
+
+# Backend uses this DSN to connect to the Postgres container.
+DATABASE_URL="postgresql+psycopg://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}"
+
+###############################################################################
+# Backend (FastAPI)
+###############################################################################
+# CORS allowlist for your Vercel app and/or custom frontend domain.
+# Example:
+# CORS_ALLOW_ORIGINS="https://easyrelocate.vercel.app,https://easyrelocate.net"
+CORS_ALLOW_ORIGINS="https://YOUR_VERCEL_APP_DOMAIN"
+
+# Enable self-serve tokens (onboarding token issuance)
+ENABLE_PUBLIC_WORKSPACE_ISSUE="1"
+PUBLIC_WORKSPACE_TTL_DAYS="30"
+
+# Optional: Google Maps server-side geocoding
+# GOOGLE_MAPS_API_KEY="YOUR_SERVER_KEY"
+# GEOCODING_PROVIDER="google"
+# ENABLE_GEOCODING="1"
+
+# Optional: OpenRouter LLM extraction for selected posts
+# OPENROUTER_API_KEY="YOUR_OPENROUTER_KEY"
+# OPENROUTER_MODEL="z-ai/glm-4.5-air:free"
+

.gitignore

@@ -21,6 +21,7 @@ dist/
 
 # Env files (do not commit secrets)
 .env
+.env.server
 .env.local
 .env.*.local
 frontend/.env

README.md

@@ -7,13 +7,13 @@ EasyRelocate is an open-source, non-commercial decision-support tool for housing
 
 When relocating for an internship, research visit, or new job, housing information is often fragmented across multiple platforms, making comparison slow and error-prone. EasyRelocate helps users organize and compare housing options by focusing on what matters most: where to live, not where to book.
 
-Users collect listings while browsing platforms such as Airbnb, Blueground, Facebook Group using a lightweight browser extension (only support Google Chrom now). EasyRelocate then aggregates the minimal, user-authorized information needed to visualize listings on a single map and compare them by price, location, and commute time to a chosen workplace.
+Users collect listings while browsing platforms such as Airbnb, Blueground, Facebook Group using a lightweight browser extension (only supports Google Chrome for now). EasyRelocate then aggregates the minimal, user-authorized information needed to visualize listings on a single map and compare them by price, location, and commute time to a chosen workplace.
 
 EasyRelocate does not scrape platforms server-side, host listings, process payments, or replace original marketplaces. It exists solely to help users make better relocation decisions, while respecting platform boundaries and directing all final actions back to the original sources.
 
 ## Repo structure
-- `backend/`: FastAPI + SQLite API
-- `frontend/`: React (Vite) web app (Google Maps JS map + routing, US-only for now)
+- `backend/`: FastAPI API (SQLite for local dev; Postgres supported via `DATABASE_URL`)
+- `frontend/`: React (Vite) web app (Google Maps JS map + routing)
 - `extension/`: Chrome extension (Manifest V3) for user-side extraction
 
 ## Configuration (API keys & env vars)
@@ -46,21 +46,45 @@ Backend reads standard env vars (auto-loads repo-root `.env` on startup):
 GOOGLE_MAPS_API_KEY="YOUR_SERVER_KEY"
 GEOCODING_PROVIDER="google"
 
-# Rrequired for the extension’s “Add selected post” feature
+# Required for the extension’s “Add selected post” feature
 OPENROUTER_API_KEY="YOUR_OPENROUTER_KEY"
 OPENROUTER_MODEL="z-ai/glm-4.5-air:free"
 
 # Optional
 ENABLE_GEOCODING="1"
 DATABASE_URL="sqlite:///easyrelocate.db"
+
+# Optional (comma-separated)
+# CORS_ALLOW_ORIGINS="https://your-vercel-app.vercel.app,https://easyrelocate.yourdomain.com"
+```
+
+## Workspaces (tokens, no user accounts)
+EasyRelocate uses **admin-created workspace tokens** instead of a user login system. All API calls (except `/api/health`) require:
+`Authorization: Bearer <workspace_token>`.
+
+Create a token (local dev / admin):
+```bash
+cd backend
+python scripts/create_workspace.py
 ```
 
+Optional (self-serve onboarding): enable `ENABLE_PUBLIC_WORKSPACE_ISSUE=1` on the backend, then the web UI can issue a 30-day token automatically via `POST /api/workspaces/issue` (see `docs/DEPLOYMENT.md`).
+
+Then paste `workspace_token` into:
+- Web app: Compare page → **Workspace** panel → Save
+- Chrome extension: Extension options → **Workspace token** → Save
+
 ### Chrome Extension (for developer)
 The extension does not read `.env` files. Configure its API base URL in Chrome:
-Extension → **Details** → **Extension options** → “API base URL” (default: `http://127.0.0.1:8000`).
+Extension → **Details** → **Extension options** → “API base URL” + “Workspace token”.
 
 ## Local dev
 
+### Quick start (backend + frontend)
+```bash
+./easyDeploy.sh --db local
+```
+
 ### 1) Backend API
 ```bash
 cd backend
@@ -84,7 +108,7 @@ Open: `http://127.0.0.1:5173` (landing page)
 Compare app: `http://127.0.0.1:5173/#/compare`
 
 Set your workplace target by:
-- Typing an address (US) and clicking **Save**, or
+- Typing an address and clicking **Save**, or
 - Clicking **Pick on map** and then clicking the map, then **Save**
 
 ### 3) Browser extension (Chrome)
@@ -113,3 +137,4 @@ See: `docs/GOOGLE_MAPS_APPROX_LOCATION.md`
 - Platform organization: `docs/PLATFORM_ORGANIZATION.md`
 - Google maps “approx street”: `docs/GOOGLE_MAPS_APPROX_LOCATION.md`
 - OpenRouter LLM extraction: `docs/OPENROUTER_LLM_EXTRACTION.md`
+- Deployment runbook (GCP managed + self-hosted): `docs/DEPLOYMENT.md`

backend/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+COPY app /app/app
+COPY scripts /app/scripts
+
+EXPOSE 8000
+
+CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+

backend/README.md

@@ -3,6 +3,21 @@
 ## Prereqs
 - Python 3.11+
 
+## Auth (workspaces, no user accounts)
+EasyRelocate uses **admin-created workspace tokens** instead of a user login system.
+
+All API calls (except `GET /api/health`) require:
+`Authorization: Bearer <workspace_token>`.
+
+Create a token:
+```bash
+cd backend
+python scripts/create_workspace.py
+```
+
+Optional (self-serve onboarding): set `ENABLE_PUBLIC_WORKSPACE_ISSUE=1` and the web UI can call
+`POST /api/workspaces/issue` to create a 30-day token (protect this endpoint in production).
+
 ## Setup
 ```bash
 python -m venv .venv
@@ -29,7 +44,7 @@ API docs:
 
 ## Geocoding (Nominatim / OpenStreetMap)
 The backend can:
-- Geocode a target address → lat/lng (US-only by default)
+- Geocode a target address → lat/lng
 - Reverse-geocode lat/lng → a rough location string (city/state)
 
 Endpoints:
@@ -39,13 +54,14 @@ Endpoints:
 Env vars:
 - `ENABLE_GEOCODING` (default `1`)
 - `ENABLE_LISTING_GEOCODE_FALLBACK` (default `0`, if `1` will approximate coords from listing city/region)
-- `GEOCODING_COUNTRY_CODES` (default `us`)
+- `GEOCODING_COUNTRY_CODES` (optional; defaults are provider-specific)
 - `GEOCODING_PROVIDER` (optional: `google` or `nominatim`)
 - `GOOGLE_MAPS_API_KEY` (optional; if set, geocoding defaults to Google)
 - `GEOCODING_USER_AGENT` (default `EasyRelocate/0.1 (local dev)`)
 - `NOMINATIM_BASE_URL` (default `https://nominatim.openstreetmap.org`)
 - `GEOCODING_TIMEOUT_S` (default `6`)
- - `DATABASE_URL` (optional; defaults to `backend/easyrelocate.db`)
+- `DATABASE_URL` (optional; defaults to `backend/easyrelocate.db`)
+- `CORS_ALLOW_ORIGINS` (optional; comma-separated allowlist for browsers)
 
 ### Google setup requirements
 If you use Google geocoding (`GEOCODING_PROVIDER=google` or `GOOGLE_MAPS_API_KEY` is set):
@@ -69,3 +85,7 @@ Env vars:
 - `OPENROUTER_TIMEOUT_S` (optional)
 
 Details: `docs/OPENROUTER_LLM_EXTRACTION.md`
+
+## Production database (Cloud SQL Postgres)
+Cloud Run instances are ephemeral. For production, set `DATABASE_URL` to Postgres (Cloud SQL).
+See: `docs/DEPLOYMENT.md`.