Installation guide

This guide is for an engineer installing and configuring the Find My Data platform — locally for evaluation and development, or on Azure for a single-tenant production deployment. It covers prerequisites, the seeded demo state, the complete FMD_* configuration reference, production boot lockouts, worker topology, and the feature-gate matrix. Current release: 26.7.15.0 (scheme year.month.day.x; see VERSION at the repo root). For what is implemented vs. mocked vs. gated, STATUS.md is the authoritative honesty ledger.

Prerequisites

Bun ≥ 1.3 (tested with 1.3.14). Bun is the only requirement — no Node.js, no database server, no Docker, no cloud credentials for the local path.

curl -fsSL https://bun.sh/install | bash

Local installation

git clone <your-clone-url> FindMyData
cd FindMyData
bun install          # install workspace dependencies
bun run seed         # create + migrate the dev database and seed the demo org
bun run dev          # start API (http://localhost:8710) + web (http://localhost:5173)

bun run dev (scripts/dev.ts) starts two processes: the API server (packages/server, Bun with --watch, default port 8710) and the Vite web dev server (packages/web, port 5173). Open http://localhost:5173 and sign in with the development persona picker (see What the seed creates). Verify the API directly:

GET http://localhost:8710/api/health → {"status":"ok"}
GET http://localhost:8710/api/ready → readiness plus per-integration modes (see Readiness and honest integration modes)

Other root scripts (from the root package.json):

Command	What it does
`bun test`	Run the test suite (`packages/shared` + `packages/server`) — 196 passing at this release
`bun run typecheck`	Strict TypeScript across all packages
`bun run lint`	oxlint over all package sources
`bun run migrate`	Apply database migrations without seeding
`bun run worker`	Run the durable worker as a standalone process (see Worker topology)
`bun run loadgen`	Generated-event load harness (see capacity model)
`bun run build`	Production build of the web app

The dev database and artifacts live under packages/server/data/ (gitignored). To reset:

rm -rf packages/server/data && bun run seed

Seed guards

bun run seed (packages/server/src/fixtures/seed-cli.ts) is a development-only operation with two hard refusals:

Exits with an error if FMD_ENV is not development.
Exits with an error if the database already contains a tenant — it never overwrites. Delete the data directory to reseed.

What `bun run seed` creates

The seed builds the complete Meridian Grove Holdings demo state (a fictional mid-market retail/logistics group — all people, groups, and documents are synthetic) by running the same services and scan pipeline the UI uses:

Tenant + org profile (industries Retail/Logistics; geographies United States/European Union) and an uploaded governance policy document.
A sensitivity-label catalog fixture.
An AI-generated taxonomy draft (deterministic mock AI provider), then governance-approved Human Resources and Finance business domains with owners assigned.
A mock Microsoft 365 connector instance (Microsoft 365 (deterministic fixture)), discovered source scopes (the HR screening drive is marked as HR’s expected/authoritative location), and a completed baseline inventory scan of every scope through the real durable pipeline.

Seeded personas (packages/server/src/fixtures/identity.ts) — one per visible role, plus a second domain owner so cross-domain isolation is always demonstrable and a second governance admin so propose ≠ approve separation of duties works on model releases:

Persona	Title	Role
Avery Chen	Platform Administrator	`platform_admin`
Sam Whitfield	Governance Lead	`governance_admin`
Lena Fischer	Model Governance Lead	`governance_admin` (second admin for separation of duties)
Priya Raman	HR Operations Director	`domain_owner` (Human Resources)
Diego Alvarez	Finance Controller	`domain_owner` (Finance)
Morgan Ellis	Information Security Manager	`remediation_approver`
Ren Nakamura	Internal Auditor	`auditor`

Fixture groups referenced by the mock tenant’s permission grants: FMD-CDX HR Screening, FMD-CDX HR Owners, Project Phoenix Team.

Configuration reference

All configuration is environment variables, parsed and validated in packages/server/src/kernel/config.ts (Zod schema; invalid values fail boot). Copy .env.example to .env as a starting point. Booleans are enabled only by the exact string true.

Secret-reference indirection (`*_REF`)

Variables ending in _REF never hold a secret. Their value is the name of another environment variable that holds the secret. Example:

FMD_GRAPH_CLIENT_SECRET_REF=GRAPH_CLIENT_SECRET   # points at the env var below
GRAPH_CLIENT_SECRET=<the actual secret>            # e.g. injected from Key Vault

This keeps secret values out of configuration files and templates; in the Azure deployment the pointed-at variable is a Key-Vault-backed Container App secret resolved by managed identity. Readiness treats a capability as configured only when the reference actually resolves to a value — a dangling reference reports blocked, never live.

Core

Variable	Type / values	Default	Effect
`FMD_ENV`	`development` \| `production`	`development`	Environment. `production` activates the boot lockouts.
`FMD_AUTH_MODE`	`dev` \| `entra`	`dev`	`dev` = seeded persona picker (banner-marked, never for production); `entra` = Microsoft Entra OIDC sign-in seam — the code flow is not implemented in this build and its endpoint responds `501` until it is (see STATUS.md and permissions manifest §1.2).
`FMD_API_PORT`	integer 1–65535	`8710`	API listen port.
`FMD_DB_PATH`	string (path)	`./data/fmd.db`	SQLite database file; created and migrated at boot (ADR-0003).
`FMD_ARTIFACT_DIR`	string (path)	`./data/artifacts`	Root directory of the purpose-flagged object/evidence artifact store.
`FMD_SESSION_SECRET`	string, min 8 chars	`dev-only-change-me`	Session-cookie signing secret; also derives the per-subscription `clientState` for change-notification verification. The default value is refused in production.

Connector mode

Variable	Type / values	Default	Effect
`FMD_CONNECTOR_MODE`	`mock` \| `graph`	`mock`	`mock` = deterministic fixture M365 tenant (the fully exercised path). `graph` = live Microsoft Graph adapter — constructed only when the Graph identifiers below are present and the secret reference resolves; otherwise every use raises an explicit `BlockedError` (never a silent mock fallback, ADR-0012). The live connector was validated read-only against the Contoso CDX tenant (ADR-0013, CDX runbook).

Microsoft Graph identifiers and secret references

Two separate app registrations by design — read/scan vs. remediation — for blast-radius containment (see permissions manifest §1.1). All are strings with no default; unset means the corresponding live path is blocked.

Variable	Identity	Effect
`FMD_GRAPH_TENANT_ID`	read/scan	Entra tenant ID for the Graph connector.
`FMD_GRAPH_CLIENT_ID`	read/scan	Client ID of the read/scan app registration.
`FMD_GRAPH_CLIENT_SECRET_REF`	read/scan	Name of the env var holding the read/scan client secret.
`FMD_GRAPH_REMEDIATION_CLIENT_ID`	remediation	Client ID of the separate remediation (label-write) app registration.
`FMD_GRAPH_REMEDIATION_CLIENT_SECRET_REF`	remediation	Name of the env var holding the remediation client secret.

AI provider

Variable	Type / values	Default	Effect
`FMD_AI_PROVIDER`	`mock` \| `azure-openai` \| `anthropic`	`mock`	Provider behind the AI gateway (ADR-0005). `mock` is deterministic, needs no credentials, and is the only provider exercised by tests. The Azure OpenAI and Anthropic adapters are built but unvalidated against live endpoints this run — readiness reports them `blocked` until their credentials resolve.
`FMD_AZURE_OPENAI_ENDPOINT`	string	—	Azure OpenAI endpoint (required for `azure-openai`).
`FMD_AZURE_OPENAI_DEPLOYMENT`	string	—	Azure OpenAI deployment name (required for `azure-openai`).
`FMD_AZURE_OPENAI_API_KEY_REF`	string (ref)	—	Name of the env var holding the Azure OpenAI API key.
`FMD_ANTHROPIC_API_KEY_REF`	string (ref)	—	Name of the env var holding the Anthropic API key (required for `anthropic`).
`FMD_ANTHROPIC_MODEL`	string	`claude-sonnet-5`	Anthropic model identifier (optional; the adapter defaults to `claude-sonnet-5` when unset).

Webhook public URL

Variable	Type	Default	Effect
`FMD_WEBHOOK_PUBLIC_URL`	string (public HTTPS base URL)	—	Base URL Microsoft Graph can reach for change notifications. The receiver endpoints are `<base>/api/webhooks/graph/notifications` and `<base>/api/webhooks/graph/lifecycle`. Without it, live subscription creation raises `BlockedError` and readiness reports `changeNotifications: blocked`. Mock-mode simulation needs no URL.

Exchange mailboxes

Variable	Type	Default	Effect
`FMD_EXCHANGE_MAILBOXES`	comma-separated list	empty	Least-privilege allowlist of the only mailboxes the live Exchange connector may read. Pair with an Exchange Online application access policy so the `Mail.Read` grant is tenant-enforced, not just app-enforced.

Control plane entitlement (licensing)

Variable	Type	Default	Effect
`FMD_ENTITLEMENT_TOKEN`	string (`<payload>.<sig>` signed token)	—	Signed entitlement issued by Find My Data Control, carrying plan (`trial`/`standard`/`enterprise`), limits (max domain owners / connected sources / assets), expiry, and an offline grace window. Verified locally — no network call.
`FMD_ENTITLEMENT_SECRET_REF`	string (ref)	—	Name of the env var holding the verification secret. This build verifies with HMAC-SHA256 (shared secret); production intent is an asymmetric public key from Control — same interface.

Without both variables the deployment runs as unlicensed. GET /api/controlplane/entitlement reports state (active / grace / expired / invalid / unlicensed), plan, expiry, and usage vs. limits. Past expiresAt but inside offlineGraceDays, the state is grace and the product keeps running.

Feature flags

All are booleans, default false, enabled only by the literal string true. See the feature-gate matrix for what each flag needs beyond itself.

Variable	Gates
`FMD_FEATURE_PURVIEW_LABEL_READ`	Live sensitivity-label observation on the Graph connector (protected `extractSensitivityLabels`). Off: the connector reports label state `unknown` — honestly, never guessing.
`FMD_FEATURE_PURVIEW_LABEL_WRITE`	Live sensitivity-label assignment (protected, metered `assignSensitivityLabel`). Also enforced at action execution time: a live-mode label action is refused when the flag is off.
`FMD_FEATURE_ENTRA_DIRECTORY_SYNC`	Reserved. Declared in the config schema but not consumed anywhere else in this build — the live directory-sync path (`User.Read.All` ownership intelligence) is not wired. Fixture principals are the exercised path.
`FMD_FEATURE_CHANGE_NOTIFICATIONS`	Live Graph change-notification subscriptions (creation and renewal).
`FMD_FEATURE_TEAMS_CONNECTOR`	Live Teams connector (per-channel message reads, gated on the protected `ChannelMessage.Read.All` permission).
`FMD_FEATURE_EXCHANGE_CONNECTOR`	Live Exchange connector (selected-mailbox message delta).

Production boot lockouts

buildConfig in config.ts enforces two startup invariants when FMD_ENV=production. Both throw ConfigError before the server binds a port — the process refuses to boot (behavior locked by kernel/config.test.ts):

Dev auth is refused. FMD_AUTH_MODE=dev fails with: FATAL: FMD_AUTH_MODE=dev is not permitted when FMD_ENV=production. Configure FMD_AUTH_MODE=entra with a valid Entra application.
The default session secret is refused. FMD_SESSION_SECRET=dev-only-change-me (or unset, which yields the default) fails with: FATAL: default FMD_SESSION_SECRET is not permitted when FMD_ENV=production.

Independently of boot, dev-session cookies are rejected at request level in production even if present. The documented seam contract (ADR-0004, permissions manifest §1.2) requires external identities to map to internal principals by (issuer, subject) — never by email or display name.

Worker topology: embedded vs. standalone

The scan pipeline runs on a durable SQLite-backed job queue (ADR-0002, ADR-0007). Two ways to run workers, same code path (startWorkerLoop):

Embedded (default). bun run dev / the API process (packages/server/src/main.ts) starts a worker loop in-process (worker ID embedded-<pid>). The embedded worker also owns the periodic sweep: renewing due change-notification subscriptions, stamping reconcile freshness, and expiring unrenewable subscriptions.
Standalone (optional). bun run worker runs packages/server/src/worker-main.ts as a separate process (worker ID worker-<pid>) against the same SQLite database and queue, with graceful SIGINT/SIGTERM shutdown. Use it to scale scanning independently of the API; multiple workers can pull from the shared queue. Note the standalone worker does not run the subscription sweep — that stays with the embedded worker in the API process.

Readiness and honest integration modes

GET /api/ready (packages/server/src/routes/health.ts) returns status (ready/degraded, HTTP 503 when the database check fails), env, and one honest mode per integration:

mock — deterministic fixture path (exercised by tests).
live — the feature is enabled and its credentials actually resolve (the *_REF points at a present value), not merely configured.
blocked — configured or enabled but a prerequisite is unmet. Never silently faked.
disabled — not enabled.

When FMD_CONNECTOR_MODE=mock, the changeNotifications, teamsConnector, and exchangeConnector capabilities report mock regardless of their flags (the dev simulator exercises those paths). One caveat, stated plainly in the permissions manifest §5: readiness computes from configuration, so setting FMD_FEATURE_PURVIEW_LABEL_WRITE=true with resolving remediation credentials shows purviewLabelWrite: live even though execution still fails at validation time without Microsoft’s protected-API enablement (the action transitions to a blocked state with the reason). Do not set feature flags ahead of their prerequisites.

Feature-gate matrix

Extra prerequisites are what the capability needs beyond FMD_CONNECTOR_MODE=graph with resolving read/scan Graph credentials (FMD_GRAPH_TENANT_ID, FMD_GRAPH_CLIENT_ID, FMD_GRAPH_CLIENT_SECRET_REF → resolving). Build-state legend: live-validated = exercised against a real tenant this run; mock-validated, live gated = full code path tested against fixtures, live path behind the gate and unvalidated; not built = no consumer.

Flag	`/api/ready` key	Capability	Extra prerequisites for live	Build state
— (connector itself)	`connector`	Graph read/scan: scope discovery, `driveItem` delta, metadata, permissions, bounded content	Admin consent for read permissions (`Sites.Selected` per-site grants recommended; CDX pilot used `Sites.Read.All` + `Files.Read.All`)	Live-validated read-only against the CDX tenant (ADR-0013)
`FMD_FEATURE_PURVIEW_LABEL_READ`	`purviewLabelRead`	Read assigned sensitivity labels via `extractSensitivityLabels`	Protected-API access (`InformationProtectionContent.Read.All`)	Mock-validated, live gated; off = label state `unknown`
`FMD_FEATURE_PURVIEW_LABEL_WRITE`	`purviewLabelWrite`	Assign/remove Purview labels (`assignSensitivityLabel`) through the draft → validate → approve → execute → verify state machine	Remediation identity (`FMD_GRAPH_REMEDIATION_CLIENT_ID` + `..._SECRET_REF` resolving), Microsoft protected/metered API enablement, write permission, synchronized label catalog (manifest §2.4)	State machine mock-validated (tested); live write gated
`FMD_FEATURE_CHANGE_NOTIFICATIONS`	`changeNotifications`	Graph `/subscriptions` wake-up hints (delta stays authoritative)	`FMD_WEBHOOK_PUBLIC_URL` — a public HTTPS endpoint Graph can validate and reach	Receiver + lifecycle + reconcile mock-validated via dev simulator; live gated
`FMD_FEATURE_TEAMS_CONNECTOR`	`teamsConnector`	Teams channels/messages (files canonicalize to SharePoint `driveItem`s)	`ChannelMessage.Read.All` consent — a protected/metered Graph capability needing Microsoft approval + licensing	Mock-validated, live gated
`FMD_FEATURE_EXCHANGE_CONNECTOR`	`exchangeConnector`	Selected-mailbox message delta + attachments	`Mail.Read` consent scoped by an Exchange application access policy; `FMD_EXCHANGE_MAILBOXES` allowlist	Mock-validated, live gated
`FMD_FEATURE_ENTRA_DIRECTORY_SYNC`	—	Directory-property sync for ownership intelligence	n/a	Not built — flag reserved, no consumer in this build

Full permission-by-permission detail, least-privilege alternatives, and protected-API caveats: permissions manifest.

Azure deployment

Single-tenant, customer-hosted deployment as Bicep — see infra/README.md for the full flow and rationale; this is the summary. The template provisions a user-assigned managed identity, Key Vault (RBAC), a storage account + file share for the SQLite database and artifacts, a Log Analytics workspace, and an Azure Container App running the API with the embedded worker, ingress on port 8710.

# 1. Validate the template
az bicep build --file infra/main.bicep

# 2. Fill in infra/main.bicepparam (non-secret identifiers only)

# 3. Deploy
az deployment group create -g <rg> -f infra/main.bicep -p infra/main.bicepparam

# 4. Set secret values out-of-band (never committed; Key Vault names:
#    fmd-session-secret, fmd-graph-client-secret)

# 5. Restart the Container App to pick them up

Key properties of the deployment:

No secrets in source control. Key Vault secrets are placeholders set out-of-band; the app reads them through Key-Vault-backed Container App secrets resolved by managed identity. The *_REF indirection is preserved: the template sets FMD_GRAPH_CLIENT_SECRET_REF=GRAPH_CLIENT_SECRET and binds GRAPH_CLIENT_SECRET to the Key Vault secret.
Production lockout active. The template sets FMD_ENV=production and FMD_AUTH_MODE=entra; the app refuses to boot with dev auth or the default session secret.
Honest scale posture. This first build is SQLite on an Azure File share with the worker embedded in the API replica. The documented scale path (managed PostgreSQL, a separate worker Container App, private endpoints, Azure OpenAI) is deliberately not provisioned to avoid implying it is done — see infra/README.md and ADR-0003.

After deploying, follow the post-deploy checklist in infra/README.md: grant the Entra app the read scopes from the permissions manifest, then confirm GET /api/ready reports the integration modes you expect — nothing claims to be live until its credentials resolve.

STATUS.md — implemented / mocked / gated honesty ledger
Architecture and ADRs
Permissions manifest — Microsoft Graph permissions and protected-API notes
CDX test runbook — live-tenant validation record and procedure
Threat model · Capacity model · Roadmap

​Installation guide

​Prerequisites

​Local installation

​Seed guards

​What bun run seed creates

​Configuration reference

​Secret-reference indirection (*_REF)

​Core

​Connector mode

​Microsoft Graph identifiers and secret references

​AI provider

​Webhook public URL

​Exchange mailboxes

​Control plane entitlement (licensing)

​Feature flags

​Production boot lockouts

​Worker topology: embedded vs. standalone

​Readiness and honest integration modes

​Feature-gate matrix

​Azure deployment

​Related documentation