A system administrator's guide: what to install, what to configure, in what order, and what each edition actually requires. Every variable, wizard step, endpoint and role below was read from the codebase, not recalled from documentation.
services/web/src/editions.ts; module counts are
Community 139 → +Governance & Assurance 254 → +Population Platform 416.
These apply to every edition and are the ones that bite if you skip them.
| Invariant | Why it matters |
|---|---|
SECRET_KEY must be set in production |
The application refuses to start with a default key in production. Generate 32+ random bytes and store it in your secret manager, never in the image. |
ENVIRONMENT=production changes seeding behaviour |
Demo accounts are not created in production. You bootstrap exactly one admin from
ADMIN_BOOTSTRAP_USERNAME / ADMIN_BOOTSTRAP_PASSWORD / ADMIN_BOOTSTRAP_EMAIL, then rotate that password immediately. |
PostgreSQL only — use Column(JSON), never JSONB |
A platform convention. Relevant if you extend the schema. |
| First boot is slow | A cold boot against an empty database runs the full seed set — roughly 3½ minutes. Warm boots are ~15 seconds. Set your readiness probe accordingly or the orchestrator will kill the pod mid-seed. |
| Never invent a role string | ROLE_HIERARCHY is validated at import. An unknown role raises at start-up and breaks migrations. To narrow what a user sees, use edition_scope (below), not a new role. |
| Variable | Purpose | Default / note |
|---|---|---|
| Required | ||
DATABASE_URL | PostgreSQL connection string | — |
SECRET_KEY | JWT signing key (HS256) | Production start-up is guarded |
JURISDICTION_ID | Active jurisdiction for this deployment | e.g. england |
ENVIRONMENT | production disables demo seeding | — |
| Commonly set | ||
SITE_URL · API_BASE_URL | Absolute URLs for links in outbound mail | — |
ALLOWED_ORIGINS | CORS allow-list — restrict it | Hardened by default |
HOME_ODS_CODE | The deploying organisation's ODS code | — |
DEFAULT_EMAIL_DOMAIN | Domain applied to seeded accounts | — |
RUNTIME_PROFILE | Deployment profile reported on /health | nas_standard |
REDIS_URL | Rate-limit / cache backend | Optional |
| Feature switches (fail-safe defaults) | ||
FEATURE_OPENEHR | openEHR CDR integration | default true; OPENEHR_URL |
FEATURE_PATIENT_PORTAL | Patient-facing portal | default false |
FEATURE_ANALYTICS | Analytics surfaces | default false |
FEATURE_OIDC | OIDC / SSO overlay | default off |
HIMSS_COCKPIT_ENABLED | HIMSS cockpit models | fail-safe ON |
P2P_SWEEP_ENABLED · P2P_SWEEP_INTERVAL_SECONDS | Policy-to-Process SLA escalation sweeper | on, 900 s |
secret_present boolean. Do not attempt to configure these through the UI; there
is deliberately no field for them.
DATABASE_URL, SECRET_KEY, JURISDICTION_ID, ENVIRONMENT.[seed] lines. Do not interrupt it.GET /health returns {"status":"ok","profile":…}. GET /capabilities reports enabled features.POST /admin/demo-data/reset. This sets a permanent flag: demo seeds never run again on that database. It is deliberately one-way.Everything jurisdictional is data, never code. The wizard at /jurisdiction-wizard
(reached from ODS Administration, /org-admin) writes a config the whole platform reads. Do this first.
| # | Step | What you supply |
|---|---|---|
| 1 | Identity | Id, display label, notes, active flag. |
| 2 | Modules | 28 module switches across Clinical / Primary Care / Operations / Jurisdiction-specific. Off by default. |
| 3 | Identifiers | Patient identifier types with format and FHIR system. Exactly one primary. Drives EMPI search, display and validation. |
| 4 | Landscape | Organisation hierarchy tiers, payers, provider types, funding model (block / PbR / capitation / mixed). |
| 5 | Governance | Model type (commissioning hierarchy / multi-payer / insurance / universal), board name, regulatory body. Templates exist for NHS England, US ACO, HSE Ireland, Saudi MOH. |
| 6 | Term overrides | Local vocabulary — what you call a "practice", a "service user", a "case". |
| 7 | Frameworks | Referral system, clinical framework, prescribing system. |
| 8 | Compliance | Standards in scope, data-residency country, whether a Caldicott Guardian is required. |
| 9 | Currencies | ISO 4217 with symbol, numeric code and decimal digits. Exactly one primary. |
| 10 | Review | Confirm and save. |
/jurisdiction-profile) exists: every
jurisdictional value is versioned, source-cited, effective-dated and signed off across 14 domains,
and a jurisdiction is not deployable until the mandatory domains are signed off and unexpired.
Resolution is nearest-wins (sovereign → sub-jurisdiction → org) and fails safe — a missing
value never falls back to another jurisdiction's.
Add a national flag for a new country in services/web/src/components/JurisdictionFlag.tsx
in the same change, or it renders a generic flag.
Role is authorisation. Edition scope is packaging. They are different things and it matters that you keep them separate.
ROLE_HIERARCHY = ["read_only", "social_worker", "care_coordinator",
"clinician", "executive", "admin", "superadmin"]UserOrganisation ODS codes. Restricted roles see only patients within their organisations.executive is oversight, not administration. It sits below admin, so it is refused by every admin-gated endpoint, and it is deliberately excluded from the unrestricted roles.User.edition_scope narrows the navigation to one edition's modules — it does
not restrict authorisation. A scoped user who types a URL directly is governed by their RBAC role
exactly as before. It also fails open: an unknown scope, or one that filters every section
away, falls back to the full navigation, so a mis-set scope can never produce a blank shell. If you
need a hard boundary, use roles and organisation scope.
Own your platform. £1 per instance with optional support. The open base plus the full NHS FDP-parity operational product set — everything the Federated Data Platform does, and deliberately none of the clinical record, which is the paid differentiator.
| Area | Where | What to do |
|---|---|---|
| Open record model | env | FEATURE_OPENEHR, OPENEHR_URL — point at your CDR. |
| Integration engine | /hl7-engine, /connector-wizard | Define inbound/outbound HL7 v2 and FHIR routes. The 8-step connector wizard covers system type → vendor → connection → auth → data streams → patient matching → schedule → test. |
| Integration assurance | /connector-dashboard | PulseGrid — set latency/error/heartbeat thresholds and the escalation ladder. Probes both source and target independently. |
| Terminology | /terminology-service | NHS_TERMINOLOGY_MODE (local|live), NHS_TERMINOLOGY_API_KEY. Crown Dependencies use the UK SNOMED CT edition under separate TRUD agreements. |
| Identity & audit | /rbac, /login-audit | Review the 18-role × 16-domain matrix. The login audit is an append-only hash chain, verified on read. |
| API gateway | /api-gateway, /api-webhook-framework | Issue API keys, set rate limits, register webhooks. |
| Jurisdiction packs | /pack-registry | Install the pack for your jurisdiction. |
Optional integrations: SMART on FHIR app launch, federated query, data products catalogue.
The FDP transition surfaces (/fdp-exit-continuity, /fdp-comparison,
/fdp-cdm) need no configuration.
Govern your organisation. Sold to boards rather than clinicians. It shares zero modules with Community or the Population Platform and contains no clinical workflow — but it still needs the Community platform base underneath (identity, audit, data fabric, API gateway).
/regulatory-engine. England→CQC/DBS, Wales→CIW/Social Care Wales, Scotland→Care Inspectorate/PVG/SSSC, NI→RQIA/AccessNI/NISCC, Ireland→HIQA are seeded. Every other jurisdiction is admin-configurable, and resolution fails safe to a generic regulator rather than another jurisdiction's./board-management: committees, terms of reference, quorum, membership. Then /board-assurance-framework: strategic objectives and principal risks./policy-to-process: scheme of reservation and delegation, financial limits, approval gates. Gates support N-of-M quorums and roles, named individuals, teams or care groups as authorisers./policy-library: import policies, set review cadence, enable version-aware attestation. Approval is signature-backed and will refuse without a completed signing ceremony./esign. Configure SMTP under Settings → Mail; the password comes from SMTP_PASSWORD in the environment and is never entered in the browser. Select the jurisdiction's signature framework (UK eIDAS, US ESIGN/UETA, and others)./ig-hub (DSPT, DPIA, breach clock, Caldicott), /ig-records (FOI on the statutory working-day clock, retention schedules, asset register + Art.30 ROPA, lineage). Optional Microsoft Purview seam: fail-safe off, PURVIEW_CLIENT_SECRET env-only./ai-governance and /ai-integration-hub. One canonical AI provider config; keys via ANTHROPIC_API_KEY / OPENAI_API_KEY / AZURE_OPENAI_API_KEY./learn, /mandatory-training, /hierarchy-builder. Load the course catalogue, assign mandatory training by role, build the care-group and supervision structure./eprr (on-call rota, eligibility pools, business continuity RTO/RPO, ICS calendar feed via EPRR_ICS_TOKEN; live comms need EPRR_SMS_ENABLED or EPRR_TEAMS_WEBHOOK, otherwise fail-safe demo), and /jurisdiction-profile sign-off.ga.admin is scoped to this
edition and works in every jurisdiction, so you can see exactly what a governance customer sees.
Non-production only — it is never seeded when ENVIRONMENT=production.
Run your health economy. Everything above, plus the longitudinal clinical record, clinical operations, flow and capacity, and population health. This is where clinical safety configuration becomes mandatory.
| Area | Where | What to do |
|---|---|---|
| Clinical record | /empi | Configure identity federation sources and patient-matching thresholds. Identifier types come from the jurisdiction config. |
| Clinical decision support | /cdss | Enable rules; set severity and override behaviour. |
| Deterioration thresholds | /config/deterioration-thresholds | NEWS2 and escalation thresholds. Review clinically before go-live. |
| Clinical safety | /hazard-log, /clinical-risk, /dcb0160 | DCB0129/0160 are mandatory. Appoint a Clinical Safety Officer, populate the hazard log, produce the safety case before clinical go-live. |
| Formulary & prescribing | /formulary | Load the formulary; DMD_MODE, DMD_BSA_BASE for dm+d. |
| National integrations | /nhs-integrations | Credential-driven adapters, each env-only: RIO_API_KEY, ERS_API_KEY, NCRS_API_KEY, NHS_LFPSE_API_KEY, NHS_SCREENING_API_KEY, NHS_BCSS_API_KEY, NHS_NHAIS_API_KEY, NHS_OPEN_EXETER_API_KEY. Each runs in honest demo mode until both an endpoint and a credential exist. |
| Patient portal | env + /patient-portal | FEATURE_PATIENT_PORTAL=true, then configure NHS Login / OTP. |
| Partner integrations | various | Luscii (LUSCII_API_KEY), Spryt ASA, Rapid Health — each behind a single switch, fail-safe off, and removable without breaking the core. |
| US deployments | /tefca | Fail-safe OFF. The technical layer is implemented; participation additionally requires legal artefacts commvita does not hold. GET /tefca/readiness enumerates them honestly. |
| Check | C | G&A | Pop |
|---|---|---|---|
SECRET_KEY set from a secret manager; bootstrap password rotated | ✓ | ✓ | ✓ |
ALLOWED_ORIGINS restricted; TLS terminated | ✓ | ✓ | ✓ |
| Jurisdiction configured; mandatory Profile domains signed off and unexpired | ✓ | ✓ | ✓ |
| Identifier validation tested against real formats | ✓ | ✓ | ✓ |
Backup and restore rehearsed (GET /admin/backup) | ✓ | ✓ | ✓ |
| Demo data reset once real data is loaded (one-way) | ✓ | ✓ | ✓ |
| Regulator resolves correctly for the jurisdiction | ✓ | ✓ | |
| Authority matrix and approval gates reflect the real SoRD/SFI | ✓ | ✓ | |
| SMTP verified — signature invitations actually deliver | ✓ | ✓ | |
| DSPT position recorded; Caldicott Guardian appointed if required | ✓ | ✓ | |
| DCB0129/0160 hazard log and safety case complete; CSO appointed | ✓ | ||
| Clinical thresholds (NEWS2, CDSS) clinically reviewed | ✓ | ||
| Patient-matching thresholds tested against real demographics | ✓ |
Every environment variable, wizard step, endpoint and role named in this guide was read from the
codebase, not recalled. Non-SaMD administrative documentation.
© 2026 Commvita Digital Health Solutions Ltd. All rights reserved.