Skip to main content

Installation Guide

Prerequisites​

  • Python 3.10+
  • Node.js 22+
  • Docker + Docker Compose
  • Postgres with pgvector

Installation & Configuration​

Local​

Backend​

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
python seeders/seed_all.py
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend​

cd ui
npm install
npm run dev

Docker​

UI + API + worker + postgres + localstack:

docker compose -f docker/docker-compose.yml up -d --build

UI + API:

docker compose -f docker/compose.ui-api.yml up -d --build

UI + API + worker:

docker compose -f docker/compose.ui-api-worker.yml up -d --build

Logging (log viewer + log tail):

docker compose -f docker/compose.logging.yml up -d

Seeders​

Run all seeders:

python seeders/seed_all.py

Run individual seeders:

python seeders/seed_states.py
python seeders/seed_districts.py
python seeders/seed_users.py
python seeders/seed_settings.py
python seeders/seed_llm_provider_types.py
python seeders/seed_llm_providers.py

Environment Variables​

All backend env vars are loaded from .env. Frontend env vars live in ui/.env.

Backend​

Path: .env

NameDefaultAllowed/Notes
DATABASE_URL(required)SQLAlchemy URL
JWT_SECRET_KEY(required)Secret for JWT signing
JWT_ALGORITHMHS256JWT algo
ACCESS_TOKEN_EXPIRE_MINUTES60Minutes
OPENAI_API_KEY(required)OpenAI key
OPENAI_CHAT_MODELgpt-5.1-miniOpenAI model
OPENAI_MODEL_TEMPERATURE1Float
OPENAI_EMBED_MODELtext-embedding-3-smallOpenAI embedding model
OPENAI_EMBED_DIMENSIONS1536Must match DB vector dim
OPENAI_TPM_LIMIT500000Tokens/min limit
OPENAI_TPM_WINDOW_SECONDS60Window size
OPENAI_TPM_SLEEP_SECONDS1Throttle sleep
OPENAI_TPM_WAIT_MAX_SECONDS120Max wait
SECRETS_PROVIDERenvenv, aws, azure
AWS_REGIONap-south-1AWS region
AWS_ENDPOINT_URLLocalStack URL if used
AZURE_KEY_VAULT_URLAzure Key Vault URL
LLM_PROVIDER_TYPEopenaiopenai, openai_compatible, gemini, anthropic, bedrock
LLM_MODELOverrides model for env provider
LLM_BASE_URLRequired only for openai_compatible
LLM_API_KEYOverrides key for env provider
LLM_TEMPERATURE0.2Overrides temperature
CHUNK_SIZE800Ingest chunk size
CHUNK_OVERLAP100Ingest overlap
EMBED_BATCH_SIZE32Embedding batch
CHUNK_COMMIT_SIZE200Commit batch
USE_WORKER_QUEUEfalseEnable worker queue; when enabled make sure worker process is running
WORKER_POLL_INTERVAL5Seconds
MAX_CONTEXT_CHARS20000Context cap
SUMMARIZATION_BATCH_CHARS6000Summarization batch
SUMMARIZATION_MAX_BATCHES10Summarization batches
ENABLE_BATCH_SUMMARIZATIONfalseSummarization toggle
CORS_ALLOW_ORIGINS*CORS
CORS_ALLOW_CREDENTIALStrueCORS
CORS_ALLOW_METHODS*CORS
CORS_ALLOW_HEADERS*CORS
STORAGE_PROVIDERlocallocal, blob, s3, gcs
PDF_STORAGE_PATH./data/pdfsLocal storage path
BLOB_CONNECTION_STRING(empty)Azure Blob
BLOB_CONTAINER(empty)Azure Blob
S3_BUCKET(empty)S3 bucket
S3_REGIONap-south-1S3 region
S3_ENDPOINT_URL(empty)LocalStack endpoint
GCS_BUCKET(empty)GCS bucket
GCS_CREDENTIALS_JSON(empty)Path to GCP service account JSON
LOG_LEVELINFOLogging level

Frontend​

Path: ui/.env

NameDefaultAllowed/Notes
VITE_API_BASEhttp://localhost:8000/apiAPI base URL
VITE_STATIC_BASEhttp://localhost:8000Static file base

Supported LLM Providers​

  • OpenAI
  • Anthropic
  • OpenAI Compatible
  • Vertex AI
  • AWS Bedrock

Supported Storage Providers​

  • AWS s3
  • GCP Storage
  • Azure blob
  • local

Supported Secret Managers​

  • AWS secret manager
  • Azure key vault