Draft a Deplpyment.md

Author: YuWei-CH

README.md

@@ -137,4 +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 (Vercel + Cloud Run + Cloud SQL): `docs/DEPLOYMENT.md`
+- Deployment runbook (GCP managed + self-hosted): `docs/DEPLOYMENT.md`

docs/DEPLOYMENT.md

@@ -1,117 +1,206 @@
-# Deployment (Vercel + Cloud Run + Cloud SQL Postgres)
+# Deployment (Engineering Runbook)
 
-This doc describes a simple production setup for EasyRelocate:
-- **Frontend**: Vercel (static hosting for the Vite app)
-- **Backend**: Google Cloud Run (FastAPI)
-- **Database**: Cloud SQL for PostgreSQL
-- **Auth**: **admin-created workspace tokens** (no user accounts)
+This doc describes two production-minded deployment options for EasyRelocate:
 
-## 1) Create Cloud SQL Postgres
+**Option A (Managed GCP)**
+- Frontend: **Vercel**
+- Backend: **Cloud Run**
+- Database: **Cloud SQL Postgres**
 
-Create a Cloud SQL Postgres instance and a database (example: `easyrelocate`), plus a DB user.
+**Option B (Self-hosted server)**
+- Frontend: **Vercel**
+- Backend + Database: **your miniPC / server** (Docker Compose)
+- Reverse proxy: **Caddy/Nginx** (HTTPS)
+- Optional exposure: **FRP**
 
-You will need:
+Both options use the same app code. The only differences are environment variables (mainly `DATABASE_URL` and CORS).
+
+## Architecture / trust boundaries
+
+- The **browser** (web app + extension) talks to your backend via HTTP(S).
+- The backend is stateless (Cloud Run or container on a server).
+- All state lives in the database (SQLite for local dev, Postgres for production).
+- Auth is **workspace tokens**:
+  - `Authorization: Bearer er_ws_...`
+  - No user accounts.
+
+## Configuration checklist
+
+### Frontend (Vercel)
+- `VITE_API_BASE_URL` = your backend public URL (no trailing slash)
+- `VITE_GOOGLE_MAPS_API_KEY` = browser key (restrict by HTTP referrer to your domain)
+
+### Backend (Cloud Run or server)
+- `DATABASE_URL` (Postgres in production; SQLite only for local dev)
+- `CORS_ALLOW_ORIGINS` = comma-separated list of allowed web origins (your Vercel domain(s))
+- Optional keys:
+  - `GOOGLE_MAPS_API_KEY` (server-side geocoding)
+  - `OPENROUTER_API_KEY` and `OPENROUTER_MODEL`
+- Optional self-serve onboarding:
+  - `ENABLE_PUBLIC_WORKSPACE_ISSUE=1`
+  - `PUBLIC_WORKSPACE_TTL_DAYS=30`
+
+## Option A — Vercel + Cloud Run + Cloud SQL Postgres
+
+### A1) Create Cloud SQL Postgres
+
+Create:
+- a Cloud SQL instance (Postgres),
+- a database (e.g. `easyrelocate`),
+- a DB user (e.g. `easyrelocate_user`).
+
+Record:
+- `DB_NAME`
 - `DB_USER`
 - `DB_PASSWORD`
-- `DB_NAME`
 - `INSTANCE_CONNECTION_NAME` (format: `project:region:instance`)
 
-## 2) Deploy backend to Cloud Run
+### A2) Deploy backend to Cloud Run
 
-### Backend env vars (Cloud Run)
+1) Containerize the backend (Docker image).
+2) Deploy the image to Cloud Run.
+3) Attach the Cloud SQL instance to the Cloud Run service (Cloud SQL connector).
+
+#### A2.1) Backend env vars (Cloud Run)
 
 Set these as Cloud Run environment variables:
-- `DATABASE_URL` (Postgres)
-- `CORS_ALLOW_ORIGINS` (comma-separated list, usually your Vercel domain(s))
-- `GOOGLE_MAPS_API_KEY` (optional, for server-side geocoding)
-- `OPENROUTER_API_KEY` (optional, for “Add selected post” extraction)
-- `OPENROUTER_MODEL` (optional; default `z-ai/glm-4.5-air:free`)
-- `ENABLE_PUBLIC_WORKSPACE_ISSUE` (optional; enable anonymous 30-day tokens)
-- `PUBLIC_WORKSPACE_TTL_DAYS` (optional; default `30`)
+- `DATABASE_URL`
+- `CORS_ALLOW_ORIGINS`
+- optional feature keys (`GOOGLE_MAPS_API_KEY`, `OPENROUTER_API_KEY`, etc.)
 
-#### `DATABASE_URL` examples
+#### A2.2) `DATABASE_URL` examples
 
-If you connect Cloud Run to Cloud SQL using the Cloud SQL connector (recommended), you can use a Unix socket host:
+Cloud SQL connector / Unix socket (recommended on Cloud Run):
 ```text
 postgresql+psycopg://DB_USER:DB_PASSWORD@/DB_NAME?host=/cloudsql/INSTANCE_CONNECTION_NAME
 ```
 
-If you use a private IP / direct host:
+Private IP / direct host:
 ```text
 postgresql+psycopg://DB_USER:DB_PASSWORD@DB_HOST:5432/DB_NAME
 ```
 
-### CORS (`CORS_ALLOW_ORIGINS`)
+#### A2.3) CORS allowlist (`CORS_ALLOW_ORIGINS`)
 
 Example:
 ```text
 https://your-vercel-app.vercel.app,https://easyrelocate.yourdomain.com
 ```
 
-Notes:
-- If you change your Vercel preview URLs often, add the stable custom domain (recommended).
-- Local dev still defaults to `http://127.0.0.1:5173` + `http://localhost:5173` when `CORS_ALLOW_ORIGINS` is not set.
+Operational note:
+- Prefer a stable custom domain. Vercel preview URLs change frequently.
 
-## 3) Deploy frontend to Vercel
+### A3) Deploy frontend to Vercel
 
-### Frontend env vars (Vercel)
+Set Vercel env vars:
+```text
+VITE_API_BASE_URL=https://YOUR_CLOUD_RUN_URL
+VITE_GOOGLE_MAPS_API_KEY=YOUR_BROWSER_KEY
+```
 
-Set these in Vercel project settings:
-- `VITE_API_BASE_URL` (your Cloud Run URL, without trailing slash)
-- `VITE_GOOGLE_MAPS_API_KEY` (browser key; HTTP referrer-restricted to your Vercel domain)
+### A4) Create workspace tokens
 
-Example:
+EasyRelocate does not ship a signup/login flow. You have two choices:
+
+#### A4.1) Admin-created tokens (recommended)
+Run the script against the same Postgres `DATABASE_URL` the backend uses:
+```bash
+cd backend
+DATABASE_URL="postgresql+psycopg://..." python scripts/create_workspace.py --ttl-days 30
+```
+
+Output:
 ```text
-VITE_API_BASE_URL=https://easyrelocate-api-xxxxx-uc.a.run.app
+workspace_id=...
+workspace_token=er_ws_...
+expires_at=...
 ```
 
-## 4) Create admin workspace tokens
+Users paste the token into:
+- Web app: Compare page → Workspace panel → Save
+- Chrome extension: Options → Workspace token → Save (use the same token)
 
-EasyRelocate does not ship a user signup/login flow. Instead, you (admin) create “workspace tokens”
-and distribute them to users. All reads/writes are scoped to a workspace.
+#### A4.2) Self-serve tokens (optional)
+Enable:
+```text
+ENABLE_PUBLIC_WORKSPACE_ISSUE=1
+PUBLIC_WORKSPACE_TTL_DAYS=30
+```
 
-If you prefer a self-serve onboarding flow (no admin distribution), you can enable:
-- `ENABLE_PUBLIC_WORKSPACE_ISSUE=1`
-- `PUBLIC_WORKSPACE_TTL_DAYS=30`
+Then the web UI can call `POST /api/workspaces/issue` to mint tokens.
 
-Then the web UI can call `POST /api/workspaces/issue` to generate a new 30-day token.
+Security note:
+- This endpoint is public. In production, add protection (rate limiting / bot protection) before
+  sharing widely.
 
-Production warning: this endpoint is public — protect it with rate limiting / bot protection.
+## Option B — Vercel + Self-hosted server (miniPC) + Postgres
 
-### Create a token (recommended workflow)
+This is the lowest “monthly bill” option if you already have hardware, but you must handle:
+patching, backups, and uptime.
 
-Run the script against the same `DATABASE_URL` your backend uses:
-```bash
-cd backend
-DATABASE_URL="postgresql+psycopg://..." python scripts/create_workspace.py
+### B1) Run Postgres + backend on the server
+
+Recommended:
+- Use Docker Compose.
+- Keep Postgres private (not exposed to the internet).
+- Expose only the reverse proxy (80/443).
+
+Minimum you need:
+- A public backend URL (e.g. `https://api.example.com`)
+- `DATABASE_URL` pointing at the Postgres container
+
+Example `DATABASE_URL` (Compose network):
+```text
+postgresql+psycopg://easyrelocate_user:DB_PASSWORD@postgres:5432/easyrelocate
 ```
 
-Output:
+### B2) Reverse proxy + HTTPS
+
+Use Caddy or Nginx to terminate HTTPS and proxy to the backend container.
+
+If you use FRP:
+- Prefer mapping FRP to 443 with TLS termination at the server (Caddy/Nginx).
+- If FRP terminates TLS upstream, ensure the backend sees correct headers and set a strict CORS allowlist.
+
+### B3) Vercel config
+
+Set:
 ```text
-workspace_id=...
-workspace_token=er_ws_...
+VITE_API_BASE_URL=https://api.example.com
 ```
 
-Treat `workspace_token` like a password.
+And on the backend:
+```text
+CORS_ALLOW_ORIGINS=https://your-vercel-domain.vercel.app,https://your-custom-domain.com
+```
 
-### Where users paste the token
+### B4) Backups (required)
 
-- **Web app**: Compare page → **Workspace** panel → paste token → Save.
-- **Chrome extension**: Extension options → **Workspace token** → Save (use the same token).
+At minimum:
+- daily `pg_dump`
+- keep 7–30 days of backups
+- periodically test restore
 
-All API calls send `Authorization: Bearer <workspace_token>`.
+## Troubleshooting
 
-## 5) Production notes
+### Frontend loads but API calls hang / abort
+- Confirm `VITE_API_BASE_URL` is correct and reachable from the browser.
+- Prefer `http://127.0.0.1:8000` for local dev (avoid IPv6-only `localhost` issues).
 
-- Cloud Run instances are ephemeral; use Postgres in production (avoid relying on local SQLite files).
-- You’ll eventually want migrations (e.g., Alembic) instead of `create_all`, but `create_all` is fine
-  for early versions.
+### 401 “Missing workspace token”
+- Ensure the workspace token is saved in:
+  - Web app Compare page → Workspace panel → Save
+  - Extension Options → Workspace token → Save
+
+### CORS errors in browser console
+- Set backend `CORS_ALLOW_ORIGINS` to include your frontend origin(s).
 
 ## Local vs cloud DB (dev convenience)
+
 If you want to keep both DB URLs in one `.env`, you can set:
 - `DATABASE_URL_LOCAL=...`
 - `DATABASE_URL_CLOUD=...`
 - `EASYRELOCATE_DB=local|cloud`
 
-For local dev, you can also use the helper script:
+For local dev, you can also use:
 `./easyDeploy.sh --db local`.