# Local Development Runbook ## Required tools - Docker Desktop or compatible Docker runtime - Node.js LTS - Python 3.11+ - Git ## Start infrastructure ```bash docker compose up -d db ``` ## Backend setup ```bash cd backend python -m venv .venv source .venv/bin/activate pip install -r requirements.txt alembic upgrade head uvicorn app.main:app --reload ``` On Windows PowerShell: ```powershell cd backend py -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt alembic upgrade head uvicorn app.main:app --reload ``` ## Frontend setup ```bash cd frontend npm install npm run dev ``` ## Worker setup ```bash cd backend rq worker geointel ``` ## Smoke checks - Backend health: `GET http://localhost:8000/health` - Frontend with Docker Compose: `http://localhost:1202` - Frontend with local Vite dev server: `http://localhost:5173` - Database: PostGIS runs on the Docker network as `db:5432`; it is not published on host port `5432` by default. - Redis: worker connects ## Common failure modes ### PostGIS extension missing Ensure the Docker image is `postgis/postgis`, not plain PostgreSQL. ### Rasterio install fails on Windows Prefer Docker backend runtime or conda/mamba environment. Do not remove Rasterio from the architecture. ### Frontend cannot reach backend For Docker Compose, rebuild/restart the frontend and verify the Vite proxy: ```bash docker compose build --no-cache frontend backend docker compose up -d bash scripts/verify_browser_runtime.sh http://localhost:1202 http://localhost:8000/health ``` `GET /api/v1/projects` on the frontend origin must return the backend JSON envelope. If it returns ``, the frontend container is stale or the nginx `/api` proxy config is not active. For local non-Docker development, `VITE_API_BASE_URL` may point directly at `http://localhost:8000`, but the default is same-origin plus a local Vite proxy. ### Worker jobs stay pending Check Redis URL and queue name.