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 guide walks you through running GeoViable on your local machine using Docker Compose. By the end you will have all three services running — the PostGIS database, the FastAPI backend, and the Nginx-served React frontend — and the environmental layer data loaded so that analysis requests return real results.
The database will contain no environmental data until you complete Step 7 (Load environmental data). Every analysis run before that point will return zero intersections and a risk score of “ninguno” — this is expected behaviour for a fresh installation, not a bug.
1

Prerequisites

Make sure the following tools are installed and available on your PATH before starting:
ToolMinimum versionPurpose
Docker24.0+Container runtime
Docker Compose2.20+Multi-container orchestration
Node.js18.x (LTS)Frontend build (npm run build)
Python3.11+Local backend development (optional)
Git—Cloning the repository
Windows users: A start.bat convenience script is included at the repository root. It wraps the key Docker Compose commands for Command Prompt / PowerShell users who prefer not to type the full commands manually.
2

Clone the repository

git clone https://github.com/danizd/geoviable.git
cd geoviable
3

Configure environment variables

Copy the provided template and open it in your editor:
cp .env.example .env
The key variables you must review and set are:
VariableDescriptionDefault
POSTGRES_DBPostgreSQL database namegeoviable
POSTGRES_USERPostgreSQL usernamegeoviable
POSTGRES_PASSWORDPostgreSQL password — change thisCHANGE_ME_SECURE_PASSWORD
DATABASE_URLSQLAlchemy connection stringpostgresql+psycopg2://geoviable:CHANGE_ME_SECURE_PASSWORD@geoviable-db:5432/geoviable
ENVIRONMENTRuntime modeproduction
LOG_LEVELPython logging verbosityINFO
CORS_ORIGINSComma-separated allowed originshttps://geoviable.movilab.es
For a production deployment, generate a cryptographically strong password with:
openssl rand -base64 32
Set the generated value in both POSTGRES_PASSWORD and the password field inside DATABASE_URL. Also update CORS_ORIGINS to your actual domain, e.g. CORS_ORIGINS=https://geoviable.movilab.es.
4

Build the frontend

The Nginx container serves React as pre-compiled static files from frontend/build/. You must build the frontend before starting Docker services for the first time, and again after any changes to frontend/src/.
cd frontend && npm install && npm run build && cd ..
This produces the production-optimised bundle in frontend/build/, which is then bind-mounted read-only into the Nginx container.
5

Start services

Build the Docker images and bring all three containers up in detached mode:
docker compose up -d --build
Check that all containers are running and healthy:
docker compose ps
You should see geoviable-db, geoviable-api, and geoviable-web all in a running state. The API container waits for the database health check to pass before starting, so allow 20–30 seconds on first boot.
Windows CRLF issue: If geoviable-api enters a Restarting loop immediately after starting, the shell scripts likely have Windows-style line endings (CRLF) that break the Linux shebang. Fix it with:
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
To prevent this permanently, add a .gitattributes file containing *.sh text eol=lf.
6

Verify installation

Once all containers are healthy, the following URLs should be reachable from your browser or curl:
ServiceURLWhat you should see
Frontendhttp://localhost:3000GeoViable React map interface
API Docshttp://localhost:8000/api/v1/docsFastAPI Swagger UI
Health checkhttp://localhost:8000/api/v1/health{"status":"healthy","database":"connected","version":"1.0.0"}
If the health check returns "database":"disconnected", check the database container logs with docker compose logs geoviable-db.
7

Load environmental data

The PostGIS database is structurally ready (tables and indexes created automatically by backend/initdb/01_init.sql on first run), but it contains no spatial data yet. Environmental layer data must be loaded manually.Request the ZIP files from daniel.zas.dacosta@gmail.com. These are pre-processed shapefiles sourced from MITECO and CNIG, clipped to Galicia and normalised to EPSG:25830.Once you have the ZIPs, place them in backend/data/ using these exact filenames:
FileLayer
red_natura_2000.zipRed Natura 2000 (ZEPA + LIC/ZEC)
zonas_inundables_t100.zipFlood zones — T100 return period
zonas_inundables_t500.zipFlood zones — T500 return period
dph.zipHydraulic Public Domain (DPH)
vias_pecuarias.zipLivestock paths
enp.zipProtected Natural Spaces (ENP)
masas_agua_superficial.zipSurface water bodies
masas_agua_subterranea.zipGroundwater bodies
Then run the loader script inside the API container:
# Optional: inspect column names and demarcation values before loading
docker compose exec geoviable-api python -m scripts.load_initial_data --inspect

# Load all layers
docker compose exec geoviable-api python -m scripts.load_initial_data
The script prints a row count for each table when it finishes. Every count should be greater than zero. If a specific layer fails, you can reload it individually using the --layer flag:
# Reload a single layer (e.g. after a failed run)
docker compose exec geoviable-api python -m scripts.load_initial_data --layer red_natura_2000
Valid values for --layer are: red_natura_2000, zonas_inundables, dominio_publico_hidraulico, vias_pecuarias, espacios_naturales_protegidos, masas_agua_superficial, masas_agua_subterranea.Once the data is loaded, open http://localhost:3000, draw a polygon over Galicia, and click Load layers — you should see coloured overlays appear on the map.

Build docs developers (and LLMs) love

Get started for freeTalk to us