Initial public release

docs/ENVIRONMENT_SPEC.md

@@ -0,0 +1,133 @@
+# 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
+
+```env
+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
+YOLO_MAX_DETECTIONS=1000
+YOLO_DUPLICATE_IOU_THRESHOLD=0.5
+ENABLE_GRB_WFS=false
+GRB_WFS_URL=
+
+# Explicit read-only source-edition probes (no provider import).
+SOURCE_CATALOG_PROBE_ENABLED=true
+SOURCE_CATALOG_GRB_WFS_URL=https://geo.api.vlaanderen.be/GRB/wfs
+SOURCE_CATALOG_STATBEL_DCAT_URL=https://doc.statbel.be/publications/DCAT/DCAT_opendata_datasets.ttl
+SOURCE_CATALOG_STATBEL_MAX_RESPONSE_MB=5
+SOURCE_CATALOG_ALZ_RELEASE_URL=https://landbouwcijfers.vlaanderen.be/open-geodata-landbouwgebruikspercelen
+SOURCE_CATALOG_PROBE_TIMEOUT_SECONDS=10
+SOURCE_CATALOG_PROBE_MAX_RESPONSE_MB=2
+SOURCE_CATALOG_PROBE_CACHE_TTL_SECONDS=900
+OSM_OVERPASS_URL=https://overpass-api.de/api/interpreter
+```
+
+The Statbel limit is separate because the official Turtle catalog is larger
+than the bounded OGC/HTML metadata responses. The probe parses only release
+metadata and validates distribution identities; it never follows population
+ZIP or XLSX links.
+
+### Frontend
+
+```env
+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:
+
+```json
+{
+  "postgis": true,
+  "rasterio": true,
+  "geopandas": true
+}
+```
+
+Verify this through the frontend proxy:
+
+```bash
+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.0.2.10:1202`.
+
+## Local development commands
+
+Backend:
+
+```bash
+cd backend
+uvicorn app.main:app --reload
+pytest
+```
+
+Frontend:
+
+```bash
+cd frontend
+npm install
+npm run dev
+npm run build
+```
+
+## Storage mounts
+
+Development storage:
+
+```text
+storage/originals
+storage/derived
+storage/tiles
+storage/masks
+storage/exports
+storage/models
+```