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.

This page covers the five most common issues encountered when deploying or running GeoViable. Work through each accordion that matches your symptoms — every entry includes a diagnosis step, a fix, and where relevant a prevention tip.
Symptom: docker compose ps shows geoviable-api in a Restarting state with exit code 255.Cause: The entrypoint.sh and/or crontab scripts were checked out with Windows CRLF line endings. On the Linux container, the CRLF characters corrupt the #!/bin/bash shebang, so the kernel cannot locate the interpreter.Diagnosis: Inspect the last few log lines from the container:
docker logs geoviable-api --tail 5
If you see exec ./entrypoint.sh: no such file or directory, the cause is CRLF line endings.Fix (PowerShell): Strip the carriage returns, then rebuild the container:
powershell -Command "(Get-Content -Raw backend\scripts\entrypoint.sh) -replace \"`r`n\",\"`n\" | Set-Content -NoNewline backend\scripts\entrypoint.sh"
powershell -Command "(Get-Content -Raw backend\scripts\crontab) -replace \"`r`n\",\"`n\" | Set-Content -NoNewline backend\scripts\crontab"
docker compose up -d --build geoviable-api
Prevention: Add a .gitattributes file to the repository root containing *.sh text eol=lf. Git will then normalise line endings automatically for every developer who clones the repository.
Symptom: The browser shows a 403 Forbidden error when accessing http://localhost.Cause: The frontend/build/ directory is empty — the React application was never compiled. Nginx has no static files to serve, so it returns 403.Diagnosis: Check whether index.html is present inside the build directory:
# Windows
dir frontend\build

# Linux / macOS
ls frontend/build
If the directory is empty or index.html is missing, the build has not been run.Fix: Install dependencies and build the React app:
cd frontend
npm install
npm run build
cd ..
This step must be completed before the first docker compose up -d and must be re-run after every change to the frontend source code. Changes to frontend/src are not picked up automatically when running under Docker — only the compiled output in frontend/build/ is served by Nginx.
Symptoms: The API returns HTTP 500 with one of these messages in the logs:
  • relation "red_natura_2000" does not exist
  • function st_geomfromgeojson does not exist
Cause: The init_db.sql script did not run when the container was first created. This happens in two scenarios:
  1. The pgdata volume already existed from a previous deployment — PostgreSQL only runs init scripts against a brand-new, empty data directory.
  2. On Windows, Docker sometimes creates backend/initdb/01_init.sql as a directory instead of a file (a known bug with kartoza/postgis and postgis/postgis images), so the schema is never applied.
Fix — universal command (works on Linux, macOS, and Windows):
# Linux / Oracle Cloud
docker exec -u postgres -i geoviable-db psql -d geoviable < backend/scripts/init_db.sql

# Windows
docker exec -u postgres -i geoviable-db psql -d geoviable < backend\scripts\init_db.sql
Verify the tables were created:
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.
Symptom: The PDF is generated without errors, but every layer shows “No” in the overlap column and ”—” for the affected area. The overall risk level is reported as NINGUNO.Cause: The environmental layer tables are empty (zero rows). This is expected behaviour on a fresh installation — the spatial data must be loaded explicitly after the database schema is created.Diagnosis: Run this query to check the record count for every layer table:
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 showing 0 needs data loaded.Fix — Option A: Manual load from ZIPs (recommended)Request the preprocessed environmental data ZIPs from daniel.zas.dacosta@gmail.com, place them in backend/data/, then run:
docker compose exec geoviable-api python -m scripts.load_initial_data
Fix — Option B: Automated update (requires internet)
docker compose exec geoviable-api python -m scripts.update_layers
Coordinate system requirement: All sample and production data must be stored in EPSG:25830 (ETRS89 / UTM zone 30N). If your source data is in UTM zone 29N (easting values roughly 680,000–730,000), it will not spatially intersect with Galicia polygons projected to zone 30N (easting values roughly 20,000–60,000 for western Galicia). The analysis will silently return zero overlaps even when the polygons visually overlap on a map.
Symptom: The API health check returns an error, or the API logs show database connection failures.Diagnosis: Verify that the PostGIS extension is installed and that the container is reachable:
docker compose exec geoviable-db psql -U geoviable -d geoviable -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'postgis';"
If the command hangs or the container is not found, check that geoviable-db is running:
docker compose ps
Fix: Open your .env file and confirm that DATABASE_URL uses the correct container name and credentials. The default value should be:
DATABASE_URL=postgresql+psycopg2://geoviable:geoviable_dev_2026!@geoviable-db:5432/geoviable
The hostname must be geoviable-db (the Docker service name), not localhost, when the API is running inside Docker Compose. After editing .env, restart the API service:
docker compose up -d geoviable-api

Build docs developers (and LLMs) love

Get started for freeTalk to us