Documentation · Getting started

Getting started

Run the Phase 1 stack from platform/: FastAPI (backend/nims), PostgreSQL, Prisma for migrations, and the React + Vite console.

Prerequisites

uv (recommended) or pip + a virtualenv under backend/
Node.js for Prisma CLI and the web app (npm install in platform/ and web/)
PostgreSQL (e.g. Docker Compose in platform/)

Configure and migrate

From platform/, copy .env.example to .env and set DATABASE_URL and JWT_SECRET.
Start Postgres (for example docker compose up -d in platform/).
Install JS deps: npm install in platform/ and npm install --prefix web (or npm ci as in CI).
Run npx prisma migrate dev and npx prisma generate as needed.
Seed: make seed or npm run db:seed (runs nims-seed via uv).

Sign-in & environment (optional)

Beyond JWT_SECRET and DATABASE_URL, you can set AUTH_LOCAL_ENABLED, AUTH_EXTERNAL_PROVIDER, and directory-specific AUTH_LDAP_*, AUTH_AZURE_*, or AUTH_OIDC_* to match your IdP. Alternatively, use the Sign-in & identity screen after seeding an admin user. See design-auth-user-management.md and platform/.env.example.

Run the API

From platform/:

make sync          # uv sync in backend
make api           # or: uv run --directory backend nims-api

Defaults: reload on, host 0.0.0.0, port 8080 (override with API_HOST, API_PORT, NIMS_RELOAD=false).

OpenAPI / Swagger: http://localhost:8080/docs
OpenAPI JSON: http://localhost:8080/docs/json
GraphiQL: http://localhost:8080/graphql
Authenticate with seed-printed API tokens: Authorization: Bearer … on GET /v1/me

Operator console (web UI)

Build the SPA so the API can serve it from web/dist at /app/: npm run web:build. For Vite dev only: npm run web:dev.

Note: npm run dev from platform/ starts the Python API, not Vite—use web:dev for the React dev server.

Copilot, LLM, and MCP (optional)

For the in-app AI assistant, set LLM_ENABLED=1 and LLM_BASE_URL / LLM_API_KEY / LLM_DEFAULT_MODEL in .env, or configure the same values in the console under Administration → LLM after an admin sign-in. Without a model, the API still returns deterministic “next step” chip fallbacks. To expose Model Context Protocol for external clients at /mcp, set NIMS_MCP_ENABLED=1 (read the security notes in design-mcp-server.md). See platform/.env.example for COPILOT_MAX_TOOL_ROUNDS and NIMS_INTERNAL_LLM_KEY (internal completion endpoint).

Background job worker (optional)

For long-running jobs and connector sync off the request path, set JOB_EXECUTION_MODE=async in .env and run a second process (same database):

uv run --directory backend nims-worker

See JOB_WORKER_POLL_INTERVAL_SEC and JOB_WORKER_BATCH_SIZE in .env.example. The default is inline execution in the API process.

CI parity

From platform/, npm run ci runs ESLint, web typecheck, web build, Ruff, and pytest (uv). See .github/workflows/platform-ci.yml for the GitHub Actions recipe.

Deploy to production (API spec, env, K8s)

Deployment & environment in this static site, and docs/deployment.md / docs/environment-variables.md on GitHub, describe the OpenAPI /docs/json contract, the Docker image, example platform/deploy Compose and Kubernetes files, and the full environment surface.

← Documentation home