LocalDevelopmentSetup.md

July 23, 2026 · View on GitHub

Supporting documentation

Overview

The local development stack runs all three services and their dependencies with Docker Compose. Python tooling is managed with uv, which creates a single environment for the whole repository. The local stack uses PostgreSQL with pgvector for retrieval and chat history so you can develop without any cloud resources.

Prerequisites

Docker Desktop or a compatible Docker engine.
uv.
Node.js if you want to run the frontend outside of Docker.

Set up the Python environment

Run this once from the repository root to create the environment.

uv sync

Start the stack

docker compose -f docker/docker-compose.dev.yml up

flowchart LR
  DEV[Developer] -->|uv sync| PY[Python env]
  DEV -->|docker compose -f docker/docker-compose.dev.yml up| COMPOSE
  subgraph COMPOSE[docker-compose dev stack]
    d_be[backend :8000]
    d_fe[frontend :5173]
    d_fn[functions :7071]
    d_az[azurite]
    d_pg[(postgres pgvector)]
    d_cos[cosmos emulator]
  end
  d_fe -->|VITE_BACKEND_URL| d_be
  d_be --> d_pg
  d_be --> d_az

Services and ports

Service	Port	Purpose
Backend API	8000	FastAPI app with hot reload. Health at `/api/health`.
Frontend	5173	React and Vite app. Reads the backend origin from `VITE_BACKEND_URL`.
Functions	7071	Ingestion worker.
Azurite	10000 to 10002	Local blob, queue, and table storage.
PostgreSQL	5432	`pgvector`-enabled database for retrieval and chat history.
Cosmos emulator	8081	Optional. Enabled with the `cosmos` profile.

The default stack pins the PostgreSQL data mode with AZURE_DB_TYPE=postgresql and AZURE_INDEX_STORE=pgvector, so retrieval and chat history both use the local database.

Profiles

Use a profile to run a subset of the stack.

# Backend and its dependencies only, no frontend
docker compose -f docker/docker-compose.dev.yml --profile backend-only up

# Frontend only, pointed at an external backend
VITE_BACKEND_URL=https://<your-backend-host> docker compose -f docker/docker-compose.dev.yml --profile frontend-only up

# Add the Cosmos DB emulator
docker compose -f docker/docker-compose.dev.yml --profile cosmos up

The backend-only profile proves the backend runs headless with no frontend dependency. The frontend-only profile serves the web app against any backend you point VITE_BACKEND_URL at.

Configuration

Copy the sample environment file and adjust values as needed.

cp .env.sample .env

The .env file is optional for the backend-only profile, so a fresh checkout boots the backend without any configuration.

Run the frontend outside Docker

To iterate on the web app with the Vite dev server, run it directly.

cd src/frontend
npm install
npm run dev

Set VITE_BACKEND_URL to the backend origin, for example http://localhost:8000.