Environment Specification

Required runtime services

Backend: FastAPI.
Frontend: Vite React.
Database: PostgreSQL with PostGIS.
Optional queue: Redis/RQ after core APIs work.

Environment variables

Backend

GEOINTEL_ENV=development
GEOINTEL_API_PREFIX=/api/v1
DATABASE_URL=postgresql+psycopg://geointel:geointel@db:5432/geointel
STORAGE_ROOT=/app/storage
MAX_UPLOAD_MB=500
YOLO_ENABLED=false
YOLO_MODEL_PATH=
YOLO_MODEL_VERSION=
YOLO_MAX_TILES=100
ENABLE_GRB_WFS=false
GRB_WFS_URL=
OSM_OVERPASS_URL=https://overpass-api.de/api/interpreter

Frontend

VITE_API_BASE_URL=
VITE_API_PROXY_TARGET=http://localhost:8000
VITE_MAP_STYLE_URL=

VITE_API_BASE_URL is intentionally empty by default so the browser calls the same origin as the frontend. In Docker Compose, nginx serves the built frontend and reverse proxies /api and /health to the backend container. For local Vite development, VITE_API_PROXY_TARGET can point to the local backend.

If VITE_MAP_STYLE_URL is empty, the frontend uses the built-in OpenStreetMap road raster basemap with visible attribution. This is suitable for local V1 testing and demos. For production, commercial use or heavier traffic, set VITE_MAP_STYLE_URL to a managed MapLibre style URL from an appropriate tile provider instead of relying on the public OpenStreetMap tile service.

Docker compose services

db: PostGIS image.
backend: FastAPI app.
frontend: nginx-served Vite build with /api and /health reverse proxy.
redis: optional, introduced when async jobs are implemented.

Docker GIS capabilities

The default backend Docker image installs the approved GIS runtime extra and system libraries needed for existing raster/vector processing:

rasterio
numpy
pillow
geopandas
pyogrio
GDAL/GEOS/PROJ runtime packages

After a Docker rebuild, the browser-facing runtime should report:

{
  "postgis": true,
  "rasterio": true,
  "geopandas": true
}

Verify this through the frontend proxy:

bash scripts/verify_gis_runtime.sh http://localhost:1202

For a LAN deployment, replace the URL with the published host address, for example http://192.168.10.150:1202.

Local development commands

Backend:

cd backend
uvicorn app.main:app --reload
pytest

Frontend:

cd frontend
npm install
npm run dev
npm run build

Storage mounts

Development storage:

storage/originals
storage/derived
storage/tiles
storage/masks
storage/exports
storage/models

2.5 KiB Raw Blame History