Jens
faeb58ef6d
GeoIntel release gates / Compile, test, contracts and builds (push) Successful in 1m49s
GeoIntel release gates / Python and npm vulnerability policy (push) Successful in 21s
GeoIntel release gates / Production AI image, SBOM and container scan (push) Successful in 5m39s
GeoIntel release gates / Deploy exact gated revision to Unraid (push) Failing after 58m43s
90 lines
1.9 KiB
Markdown
90 lines
1.9 KiB
Markdown
# 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.
|