Run locally

Local mode runs the full app on your machine, with one exception: embedding and generation calls go to real AWS Bedrock using your credentials, since Bedrock has no local emulator. The vector store runs locally as Postgres + pgvector in Docker.

Prerequisites

• Docker (Compose v2+)
• uv — manages Python 3.12+, no separate venv/pip steps
• Node.js 24+ (frontend and this docs site)
• AWS credentials with Bedrock access in us-east-1 (for ingestion and the query API)

First-time setup

git clone https://github.com/ArunskiOrg/rag-sample-app.git
cd rag-sample-app

make setup   # env + frontend-install + db-up + install + migrate, in one shot

make setup runs, in order: copy .env.example to .env, install frontend deps, start the Postgres+pgvector container, uv sync --all-extras (creates backend/.venv, installs api + ingestion + dev extras), and apply the database schema (rag-migrate).

Then install pre-commit hooks (one-time, not part of make setup):

uv tool install pre-commit --with pre-commit-uv
pre-commit install
pre-commit run --all-files   # backfill against the existing tree

Running

# Ingest the corpus (embeds via Bedrock; one-time, requires Bedrock creds)
make ingest-all              # add LIMIT=N to cap rows for a fast local smoke test

# Query API (FastAPI), reload on change
make api

# Issue yourself an API key for the query endpoint
make key-issue                # add RECIPIENT=you@example.com to label it

# Frontend chat UI (separate terminal)
make frontend-install         # first time only
make frontend                 # proxies to the API on :8000

For frontend work with no AWS/DB dependency at all, run make frontend-mock (mock backend on :8000) instead of make api, then make frontend against it.

Common targets

Run make help for the full list. Frequently used:

Target	What it does
make db-up / make db-down / make db-logs	Manage the local pgvector container
make migrate	Apply pending SQL migrations
make ingest-load / make ingest-embed / make ingest-all	Corpus ingestion steps (add LIMIT=N / BATCH=N)
make key-issue / make key-revoke / make key-list	Manage local API keys
make test / make test-file FILE=...	Backend test suite (pytest)
make lint / make fmt	ruff check / format
make frontend-test	Frontend tests with coverage
make export-openapi	Regenerate backend/openapi.json from the FastAPI app

This docs site

cd docs-site
npm install
npm run dev      # http://localhost:4321