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.

GeoViable runs as a three-container Docker Compose stack: a PostGIS spatial database, a FastAPI backend with PDF generation and scheduled layer updates, and an Nginx server that hosts the React frontend and acts as a reverse proxy to the API. All inter-service communication happens over an internal bridge network — only Nginx exposes ports to your host machine.

​
Prerequisites

Install the following tools before you begin:
ToolMinimum VersionPurpose
Docker24.0+Container runtime
Docker Compose2.20+Service orchestration
Node.js18.x LTSFrontend build only
Git—Source control

​
Container Overview

ContainerImageInternal PortPurpose
geoviable-dbpostgis/postgis:15-3.45432PostgreSQL + PostGIS spatial database
geoviable-apipython:3.11-slim (custom)8000FastAPI + WeasyPrint + cron
geoviable-webpublic.ecr.aws/docker/library/nginx:1.25-alpine80Static files + reverse proxy
All three containers communicate over the geoviable-net bridge network. Only geoviable-web exposes ports to the host (3000:80). In the default local development compose file, geoviable-api also exposes port 8000 directly so you can reach the API docs and health endpoint without going through Nginx.

​
Setup Steps

1

Clone the repository

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

Configure environment variables

Copy the example file and edit it with your preferred values. See the Environment Variables page for a full reference of every setting.
cp .env.example .env
3

Build the React frontend

Nginx serves the frontend as compiled static files from frontend/build/. The build must exist before the containers start — an empty build/ directory will cause Nginx to return 403 Forbidden.
cd frontend && npm install && npm run build && cd ..
4

Start all services

docker compose up -d --build
Docker builds the backend image (which installs system dependencies for WeasyPrint and GDAL), pulls the PostGIS and Nginx images, and starts all three containers.
5

Check container status

docker compose ps
All three containers should show Up (or Up (healthy) for geoviable-db and geoviable-api once their health checks pass).
6

Verify the installation

Once all containers are healthy, open the following URLs to confirm each service is running:
ServiceURLExpected response
Frontendhttp://localhost:3000GeoViable React application
API Docshttp://localhost:8000/docsFastAPI Swagger UI
Health Checkhttp://localhost:8000/api/v1/health{"status": "ok"}
7

Load environmental data

On a fresh installation the PostGIS database has no environmental layers loaded. Analyses will run but return no spatial intersections until you load the data. Follow the Loading Data guide to populate all seven layers.

​
Useful Docker Commands

​
Stream logs in real time

docker compose logs -f
To follow a single service only: 
docker compose logs -f geoviable-api

​
Access the database directly

docker compose exec geoviable-db psql -U geoviable -d geoviable

​
Rebuild a single service

Use this after changing backend Python code or the Dockerfile — Docker will only rebuild geoviable-api and leave the database untouched: 
docker compose up -d --build geoviable-api

​
Full reset

docker compose down -v deletes the pgdata volume, destroying all data in the database. You will need to reload all environmental layers afterwards. Only run this if you want a completely clean slate.
docker compose down -v

​
Frontend Rebuild Workflow

Because Nginx serves the compiled frontend/build/ directory as read-only static files, changes to React source code are not reflected until you rebuild: 
cd frontend && npm run build
docker compose restart geoviable-web
You do not need to rebuild the Docker image to pick up frontend changes — restarting Nginx is sufficient because the frontend/build/ directory is mounted as a volume.

​
Windows Notes

On Windows, use start.bat to start the services instead of running docker compose directly.
If geoviable-api enters a restart loop with exit code 255 and docker logs geoviable-api shows exec ./entrypoint.sh: no such file or directory, the cause is Windows CRLF line endings in entrypoint.sh. Fix it before rebuilding:
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

​
Platform Notes

ARM64 (Apple Silicon, Raspberry Pi, Oracle Ampere): All images used by GeoViable — postgis/postgis, nginx:1.25-alpine, and python:3.11-slim — ship multi-arch manifests and support linux/arm64 natively. No --platform flag is needed.
Docker Hub unreachable? Both the Nginx image (geoviable-web) and the Python base image used in the backend Dockerfile are referenced via the AWS ECR Public mirror (public.ecr.aws/docker/library/). If Docker Hub is rate-limited or unreachable on your network, the images will be pulled from ECR Public automatically without any configuration change.

Build docs developers (and LLMs) love

Get started for freeTalk to us