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
1.9 KiB
1.9 KiB
Local Development Runbook
Required tools
- Docker Desktop or compatible Docker runtime
- Node.js LTS
- Python 3.11+
- Git
Start infrastructure
docker compose up -d db
Backend setup
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:
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
cd frontend
npm install
npm run dev
Worker setup
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 port5432by 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:
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.