Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danizd/geoviable/llms.txt

Use this file to discover all available pages before exploring further.

Use this page when something isn’t working — run these commands in order to identify the problem. Each step narrows down the root cause so you can jump directly to the relevant fix in the common issues guide.
1

Check container status

Run docker compose ps to confirm all three services are running:
docker compose ps
All containers — geoviable-api, geoviable-db, and geoviable-web — should show status Up. Any service in Restarting or Exited state is the likely source of the problem.
2

Check API logs

Stream the most recent API log lines and look for ERROR entries:
docker compose logs -f geoviable-api --tail 30
Common error patterns to look for:
  • exec ./entrypoint.sh: no such file or directory → CRLF line ending issue (see Issue 1)
  • relation "..." does not exist → missing database tables (see Issue 3)
  • could not connect to server → database connectivity problem (see Issue 5)
3

Health check endpoint

Verify that the API is up and connected to the database:
curl http://localhost:8000/api/v1/health
Expected response when everything is healthy:
{"status": "healthy", "database": "connected"}
The health endpoint returns HTTP 503 (not 200) when the database is unreachable. A 503 here means the API process started successfully but cannot talk to geoviable-db — check your .env DATABASE_URL and confirm the database container is running.
4

Verify PostGIS extension

Confirm that the PostGIS extension is installed in the geoviable database:
docker exec geoviable-db psql -U geoviable -d geoviable -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'postgis';"
You should see one row with extname = postgis and a version of 3.4 or higher. An empty result set means the extension was never installed — re-run init_db.sql as described in Issue 3.
5

Verify tables exist

List all tables in the database:
docker exec -u postgres geoviable-db psql -d geoviable -c "\dt"
You should see 8 tables: the 7 environmental layer tables plus layer_update_log. If any are missing, the schema initialisation did not complete — follow the fix in Issue 3.
6

Check layer record counts

Confirm that every environmental layer table contains data:
docker exec geoviable-db psql -U geoviable -d geoviable -c "
  SELECT 'red_natura_2000' AS tbl, count(*) FROM red_natura_2000
  UNION ALL SELECT 'zonas_inundables', count(*) FROM zonas_inundables
  UNION ALL SELECT 'dominio_publico_hidraulico', count(*) FROM dominio_publico_hidraulico
  UNION ALL SELECT 'vias_pecuarias', count(*) FROM vias_pecuarias
  UNION ALL SELECT 'espacios_naturales_protegidos', count(*) FROM espacios_naturales_protegidos
  UNION ALL SELECT 'masas_agua_superficial', count(*) FROM masas_agua_superficial
  UNION ALL SELECT 'masas_agua_subterranea', count(*) FROM masas_agua_subterranea;
"
All counts should be greater than 0. Any table with 0 rows will cause the analysis to return no overlaps for that layer. Follow the data-loading steps in Issue 4 to populate empty tables.
7

Test the analyze endpoint

Send a sample polygon that falls within Galicia to confirm the spatial analysis pipeline works end-to-end:
curl -X POST http://localhost:8000/api/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-8.65,42.95],[-8.55,42.95],[-8.55,43.02],[-8.65,43.02],[-8.65,42.95]]]},"properties":{}}'
A successful response is a JSON object containing layer overlap results. An error response will include an error code — consult the API error codes table below for the meaning.
8

Check layer update status

Query the layer status endpoint to see when each layer was last updated and how many records it holds:
curl http://localhost:8000/api/v1/layers/status
The response includes last_updated and records_count per layer. Layers that have never been loaded will show null for last_updated.
9

Check the update log

Inspect the cron-driven layer update log for any errors from the most recent automated run:
docker compose exec geoviable-api tail -50 /var/log/geoviable_update.log
This file is written by scripts/update_layers.py each time the monthly cron job fires. Look for Python tracebacks or download failures that would explain stale or missing layer data.

​
Log Locations

LogHow to access
API application logsdocker compose logs -f geoviable-api
Nginx access/error logsdocker compose logs -f geoviable-web
Database logsdocker compose logs -f geoviable-db
Layer update cron logdocker compose exec geoviable-api tail -f /var/log/geoviable_update.log

​
API Error Codes Reference

CodeHTTPMeaning
INVALID_JSON400Request body is not valid JSON
INVALID_GEOJSON400Body is not a valid GeoJSON Feature
INVALID_GEOMETRY_TYPE400Geometry must be Polygon or MultiPolygon
MULTIPLE_FEATURES400Only 1 polygon allowed per request
INVALID_TOPOLOGY400Polygon is self-intersecting
OUT_OF_BOUNDS400Polygon is outside the Galicia bounding box
AREA_TOO_LARGE400Polygon area exceeds 100 km²
TOO_MANY_VERTICES400Polygon has more than 10,000 vertices
QUERY_TIMEOUT504PostGIS spatial query exceeded the 30-second timeout
ANALYSIS_FAILED500Internal spatial analysis error
MISSING_PROJECT_NAME422project.name is required in the request body
PROJECT_NAME_TOO_LONG422project.name exceeds 100 characters
MISSING_GEOJSON422geojson field is absent from the request body
PDF_GENERICATION_FAILED500WeasyPrint PDF generation error
Once you’ve identified the failing component, head to Common Issues for step-by-step fixes for each of these problems.

Build docs developers (and LLMs) love

Get started for freeTalk to us