Skip to content

Getting started: run RA locally and make your first call

This tutorial takes you from a fresh clone to a running Research Assistant backend and a first successful API call, using the Docker-based local development stack. By the end you will have the API serving on http://localhost:8000 and will have read a live response from it.

This is a learning walkthrough. For the condensed task version, see Run RA locally.

Prerequisites

From the repository README.md:

  • Python 3.11 or 3.12 with uv
  • Docker + Docker Compose (do not install Docker Desktop — see the README)
  • Azure CLI (az) — used for runtime Azure access
  • Node.js 18+ (only needed if you also want to run the frontend)

1. Clone and fetch submodules

RA vendors altaforge and logicstream as git submodules. make setup-dev-env initialises them for you, but if you are cloning by hand, pull them explicitly:

git clone --recurse-submodules <repo-url> altaforge-ra
cd altaforge-ra
# or, if you already cloned without --recurse-submodules:
git submodule update --init --recursive

No Azure DevOps feed or token is needed to install dependencies — they resolve from the two submodules.

2. Authenticate with Azure

az login

This is for runtime Azure access (OpenAI, Search, blob storage). It is not used to fetch packages.

3. Configure environment

Non-secret defaults are already committed in backend/.env, so there is nothing to copy there. Hydrate secrets from Azure Key Vault (this needs the VPN), then set your own tenant id:

make env                        # hydrates backend/.env.local + rag_pipeline/.env.local from Key Vault
make set-dev-organization-id    # writes a per-developer ORGANIZATION_ID (also drives your own search index)

ORGANIZATION_ID has no committed default because it is the tenant this deployment serves. The Azure AI Search index name is derived from it (ra-{organization_id}), so setting your own keeps you from overwriting another developer's index. make set-dev-organization-id derives the UUID from a slug (default is your machine's identity; override with ORG_SLUG=my-slug) and writes it to backend/.env.local, rag_pipeline/.env.local, and frontend/.env.local.

For a first run you do not need to configure real authentication — the dev stack sets DISABLE_AUTH=true so every request is served as a hardcoded dev admin user.

4. Install dependencies

make setup-dev-env

This initialises submodules (if needed) and installs backend, frontend, and rag_pipeline dependencies with uv.

5. Run the stack

make run-dev

This starts, in attached mode (logs stream to your terminal; press Ctrl+C to stop):

  • Backend API on http://localhost:8000
  • Frontend on http://localhost:5173
  • SQL Server 2022 (local database)
  • Redis (shared L2 cache)
  • Azurite (Azure Storage emulator)

The migrate init service applies Alembic migrations before the backend starts, and a one-shot seed-org-auth-config service seeds your dev org's auth config — no manual step required.

Note: Azure AI Search cannot be emulated locally. The API will start and serve without it, but a research query that performs retrieval needs a real Azure AI Search service configured in your .env.local. The calls in step 6 do not require it.

6. Make your first call

Wait until the logs show the server is ready, then check the readiness probe (no auth required):

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

Now call an authenticated endpoint. Because the dev stack runs with DISABLE_AUTH=true, any bearer token is accepted — but you must still send the X-Organization-Id header, because RA is multi-tenant and has no default tenant. Use the org id make set-dev-organization-id wrote to backend/.env.local:

ORG_ID=$(grep '^ORGANIZATION_ID=' backend/.env.local | tail -1 | cut -d= -f2-)

curl http://localhost:8000/config \
  -H "X-Organization-Id: $ORG_ID" \
  -H "Authorization: Bearer dev"

You should get the tenant's frontend feature flags, e.g.:

{
  "ff_enable_escalation_request_admin": false,
  "enable_escalation_workflow": false,
  "manual_escalation_enabled": false,
  "enable_quick_links": false,
  "ff_enable_ip_allowlist_admin": false
}

If you omit X-Organization-Id, the request is rejected with 400 — this is the multi-tenant contract, not a bug.

7. Explore the interactive API docs

Open the auto-generated Swagger UI in a browser:

http://localhost:8000/docs

Every endpoint, request model, and response model is documented there, generated live from the running app. The same surface is described in the HTTP API reference.

8. Stop the stack

Press Ctrl+C in the terminal running make run-dev to stop the containers while preserving data. For a full reset (drops the database volume):

make down-dev

Where to go next