How to run RA locally¶

Get the Research Assistant backend running on your machine for development. This is the condensed task version of the getting-started tutorial.

Option A: full Docker stack (recommended)¶

From the repository root:

az login                       # runtime Azure access
make setup-dev-env             # init submodules + install backend/frontend/rag_pipeline deps
make env                       # hydrate secrets from Key Vault (needs VPN)
make set-dev-organization-id   # write a per-developer ORGANIZATION_ID
make run-dev                   # start backend + frontend + SQL Server + Redis + Azurite

Services:

Service	URL
Backend API	`http://localhost:8000`
Interactive API docs (Swagger)	`http://localhost:8000/docs`
Frontend	`http://localhost:5173`

make run-dev runs attached — logs stream to the terminal; press Ctrl+C to stop. Migrations are applied by the migrate init service before the backend starts; the dev org's auth config is seeded automatically by the seed-org-auth-config service.

To include the RAG ingestion pipeline as well:

make run-rag-pipeline-dev      # everything above + the RAG pipeline Azure Function on :7071

Stop and reset:

make down-dev                  # stop + remove containers, networks, volumes (full reset)

Option B: backend only, without Docker¶

You must supply your own SQL Server (or PostgreSQL) and Azure Storage (or Azurite). Then:

cd backend
uv sync
uv run uvicorn altaml_research_assistant.server:app --reload --host 0.0.0.0 --port 8000

Apply pending migrations first when running outside Docker:

cd backend
DATABASE_URL="..." uv run alembic upgrade head

Local authentication¶

The dev stack sets DISABLE_AUTH=true, which activates FakeAuthBackend: every request is served as the hardcoded user dummy.user@altaml.com, and any bearer token is accepted without validation. You still must send the X-Organization-Id header on every request — RA has no default tenant.

Change the local user's role by editing the anchor at the top of compose.dev.yaml and restarting:

# compose.dev.yaml
x-fake-auth-user-type: &fake_auth_user_type "Admin"   # Admin | User | VirtualUser | PlatformOperator

Value	Role granted
`Admin` (default)	`App.Admin.FullAccess`
`User`	`App.User.ReadOnly`
`VirtualUser`	`App.User.Virtual`
`PlatformOperator`	`App.Platform.Operator` (needed to exercise `/platform/*`)

Warning: DISABLE_AUTH and FAKE_AUTH_USER_TYPE are local-development only. They bypass authentication entirely and must never be set in a deployed environment.

Verify it is up¶

curl http://localhost:8000/health/ready     # {"status":"ok"} once startup completes

/health/ready returns 503 until the app's lifespan startup finishes, then 200. /health/live always returns 200 while the process is running. Both are unauthenticated.

Common environment variables¶

Full reference lives in backend/README.md (Environment Configuration) and the secrets contract in backend/env.secrets.toml. The ones you are most likely to touch locally:

Variable	Purpose
`ORGANIZATION_ID`	The tenant this backend serves; also derives the search index name `ra-{organization_id}`. Set via `make set-dev-organization-id`.
`DISABLE_AUTH`	`true` in the dev stack to bypass auth.
`DATABASE_URL`	SQLAlchemy async URL (MSSQL `mssql+aioodbc://…` or PostgreSQL `postgresql+asyncpg://…`).
`REDIS_URL`	Shared L2 cache; injected automatically under Docker Compose.
`LOG_LEVEL`	Root log level (default `INFO`; set `DEBUG` for per-request diagnostics).
`AZURE_LLM_ENDPOINT`, `AZURE_LLM_DEPLOYMENT_NAME`, `AZURE_LLM_API_VERSION`	Azure OpenAI for answer synthesis and all shared LLM calls.
`AZURE_AI_SEARCH_ENDPOINT`	Azure AI Search service (cannot be emulated locally).