Skip to main content

Local Development

Python-First Development​

The API can be run outside Docker, but you need system geospatial bindings.

Minimum requirements:

  • Python 3.10+
  • GDAL and Python GDAL bindings
  • MapServer binaries and Python MapScript bindings
  • Redis and Celery if you need async job execution

Example installation flow on Debian or Ubuntu:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install fastapi uvicorn pydantic celery PyYAML
sudo apt-get install -y gdal-bin python3-gdal mapserver-bin python3-mapscript

Run the app:

export DATA_ROOT="$PWD/data"
uvicorn app:app --reload --host 0.0.0.0 --port 8080

Docusaurus Development​

The documentation site lives in docs-site/.

cd docs-site
npm install
npm run start

This launches a standalone docs dev server. The production stack does not use that server; it builds static assets and serves them from FastAPI at /guide/.

API Image Build Behavior​

The Docker image now includes a docs build stage:

  1. Node installs the Docusaurus dependencies.
  2. npm run build generates static assets.
  3. The built files are copied into /opt/fastapi-mapserver-docs.
  4. FastAPI mounts that directory at /guide when it exists.

This keeps the runtime image free of Node.js while preserving same-stack hosting.

Local Swarm Caveat​

local-stack.yml bind-mounts the repository into /app, so anything that must survive the bind mount needs to live outside /app. That is why the docs build is copied to /opt/fastapi-mapserver-docs in the image rather than being served from the repository tree inside the container.