Initial GeoIntel V1 foundation

2026-06-16 23:36:32 +02:00
commit 6ea3586a3e
605 changed files with 45284 additions and 0 deletions
@@ -0,0 +1,89 @@
+# 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 `<!doctype html>`, 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.