Skip to main content

Quick start

Two ways to run stacgis-ai: Docker Compose (one command, recommended) or a manual setup with local Python + Node.

Option A — Docker Compose​

1. Prerequisites​

  • Docker with the Compose plugin
  • An LLM — e.g. Ollama on your machine (ollama pull qwen3.5:9b or any model you like)

2. Clone the repository​

git clone https://codeberg.org/stac-gis/geo-ai stacgis-ai
cd stacgis-ai

3. Configure the environment​

cp .env.example .env
VariableDefaultMeaning
OLLAMA_BASE_URLhttp://host.docker.internal:11434Where the backend finds your LLM
OLLAMA_MODELqwen3.5:0.8bModel name (must exist on that LLM server)
BACKEND_PORT8000Host port for the FastAPI service
FRONTEND_PORT3000Host port for the chat UI

:::tip Ollama in Docker too? Use docker compose --profile ollama up --build and set OLLAMA_BASE_URL=http://ollama:11434 in .env. :::

4. Build & start​

docker compose up --build

The stack builds both packages (backend with uv, frontend with npm/Vite) and runs the example apps — no local Python/Node setup required.

5. Verify​

ServiceURL
Frontendhttp://localhost:3000
Backendhttp://localhost:8000 (Swagger at /docs)

Open the chat UI and ask the agent to geocode a place, route between two cities or find POIs. Watch it stream its ReAct steps and emit GeoJSON.

6. (Optional) Run the tests​

# Backend (Python ≥ 3.11 + uv)
cd backend && uv sync --extra mcp --extra dev && uv run python -m pytest

# Frontend (Node ≥ 18)
cd frontend && npm install && npm run build

Option B — manual setup (no Docker)​

1. Prerequisites​

  • Python ≥ 3.11 + uv
  • Node.js ≥ 18 + npm
  • A running LLM (e.g. Ollama on http://localhost:11434)

2. Clone & configure​

git clone https://codeberg.org/stac-gis/geo-ai stacgis-ai
cd stacgis-ai
export OLLAMA_BASE_URL=http://localhost:11434
export OLLAMA_MODEL=qwen3.5:9b

3. Start the backend​

cd backend
uv sync --extra mcp --extra examples   # install stacgis-ai + MCP support
uv run python run_example.py           # serve on http://localhost:8000

4. Verify the API​

# blocking chat
curl -X POST http://localhost:8000/api/v1/agent/chat \
  -H 'Content-Type: application/json' \
  -d '{"message": "Find 5 cafes near London and buffer them by 200 m"}'

# streaming (SSE)
curl -N -X POST http://localhost:8000/api/v1/agent/stream \
  -F 'message=Route from Paris to Lyon'

5. Build & run the frontend​

cd ../frontend
npm install
npm run build                # build the library (dist/)

cd example
npm install
npm run dev                  # http://localhost:3000 — talks to the backend above

6. Run the tests​

cd ../backend && uv run python -m pytest
cd ../frontend && npm run build && (cd example && npm run build)