Adrian Bernhard
← Technical docs

03 · Radiology

Orthanc: technical overview

The radiology institute: an Orthanc PACS with DICOMweb and a small RIS served as FHIR R5.

Synced from source on 26 October 2026

Orthanc is the radiology institute in a demo healthcare sandbox. It runs a PACS (image archive) with DICOMweb, a small RIS (patient registry, orders, radiology reports) exposed as FHIR R5, a gateway that enforces "open reads, gated writes", a browse UI with a DICOM viewer, and a front desk that links its patients to the patient portal.

This document describes the system as Orthanc's code and configuration implement it.

Public URL: https://dicom.adrianbernhard.ch. All data is fictional patients attached to real, openly licensed research images.


1 Overview#

The sandbox models a small Swiss healthcare landscape as independent systems:

System Role FHIR version
Erebor (fhir.adrianbernhard.ch) the hospital (HAPI FHIR) R4
Orthanc (dicom.adrianbernhard.ch) an independent radiology institute (PACS + RIS) R5
Imladris (portal.adrianbernhard.ch) patient portal that links a person's records across institutions consumer of both

Orthanc deliberately looks like a separate organisation: its own patient IDs (OR- plus five digits), its own accession numbers (ORT-YYYY-NNNNNN), its own spelling of some names, and its own FHIR version. Reconciling it with the hospital is the portal's job, not Orthanc's.

What a visitor or client can do:

  • browse and search patients and their exams in a terminal-styled web UI;
  • read radiology reports and open studies in a Cornerstone3D viewer;
  • query images over DICOMweb (QIDO-RS, WADO-RS) and the Orthanc REST API;
  • query the RIS over a read-only FHIR R5 API (/fhir);
  • as institute staff, link a portal account to an Orthanc patient at the front desk (/desk).

Current content (GET /statistics and GET /ris/status show the live numbers): 8 patients, 43 studies, 178 series, about 4,200 instances (about 2.4 GB); 61 orders and 61 reports, 24 practitioners, 4 organisations, 8 coverages.

The imaging data#

Every image is a real research study from the NCI Imaging Data Commons (TCIA and Zenodo collections, CC BY 3.0 / 4.0), relabelled to a fictional patient: the patient, date, institution and trial fields in the DICOM header are rewritten, the pixel data is unchanged. The full source list with citations is at /credits.

No face, skull or brain studies. The curation rule (applied by the separate curation pipeline that builds the data set) is: no head, brain, face, skull or neck cross-sectional imaging (CT, MR, PET), and no 3D volume whose field of view includes the head or face. The reason is privacy: a 3D head volume can be rendered into a recognisable face, which a header rewrite cannot anonymise. 2D projection radiographs (CR/DX) are allowed even when the chin or neck is incidentally in frame, as on chest films, and the curator stops if a 2D image shows an identifiable face. The relabelling script rejects any study whose BodyPartExamined is HEAD, BRAIN, SKULL, HEADNECK, NECK, FACE or WHOLEBODY. Orthanc itself only states the rule (the UI intro and the credits page); the server and the gateway do not check it at upload time.


2 Architecture#

flowchart LR
    subgraph clients[Clients]
        browser[Browser: explorer UI and viewer]
        portal[Imladris patient portal]
        staff[Institute staff at the front desk]
        curl[API clients, curl]
        uploader[Curation scripts with write key]
    end

    subgraph host[Single Coolify host]
        proxy[Coolify / Traefik reverse proxy, TLS]
        subgraph gw[Gateway: Node 22 + Express]
            csp[CSP headers]
            desk[Front desk /desk + identity check]
            static[Static UI + bundled viewer]
            readgate[Read allowlist for GET/HEAD]
            limits[Per-IP rate limits]
            writegate[Write key gate + keyed write allowlist]
            ris[RIS FHIR layer /fhir and /ris]
            store[(RIS store: registration Bundle in memory, JSON on a volume)]
            inject[Inject Orthanc Basic Auth, strip X-API-Key]
        end
        subgraph pacs[Orthanc PACS, not publicly exposed]
            core[Orthanc core REST API]
            dicomweb[DICOMweb plugin]
            fhirplugin[orthanc-java FHIR plugin, HAPI R5]
        end
        pg[(PostgreSQL 16: Orthanc index)]
        files[(Volume: DICOM files)]
    end

    browser --> proxy
    portal --> proxy
    staff --> proxy
    curl --> proxy
    uploader --> proxy
    proxy --> csp --> desk --> static --> readgate --> limits --> writegate --> ris --> inject
    desk -. reads patients .-> store
    desk -. lookup / redeem link codes .-> imladris_api[Imladris institution API]
    ris -. RIS resources .-> store
    ris -- ImagingStudy, Endpoint, plugin Patients --> fhirplugin
    inject --> core
    inject --> dicomweb
    fhirplugin --> dicomweb
    core --> pg
    core --> files

Three containers run from one Docker Compose file: PostgreSQL, Orthanc, and the gateway. Only the gateway has a published port; Orthanc is reachable only on the internal Compose network, and it still requires its own Basic Auth there.

Request path through the gateway (order matters, see gateway/app.js):

  1. Security headers (CSP, HSTS, nosniff) are set on every response.
  2. Front desk (/desk, /desk/api/*) is handled first and never reaches Orthanc.
  3. CORS (*) and static files (public/: explorer, credits, viewer bundle).
  4. Read allowlist: a GET/HEAD not matched by a static file must be on an explicit allowlist, otherwise 404. This is what keeps Orthanc's own admin UI (/app/...) unreachable.
  5. No FHIR operations: any $operation on /fhir is 403.
  6. Rate limits per client IP, in three groups (section 7).
  7. Write gate: POST/PUT/PATCH/DELETE need X-API-Key, except two read-only POSTs (/tools/find, /tools/lookup); with the key, only a short list of writes is allowed (section 7).
  8. RIS router owns /fhir/* and /ris/*.
  9. Auth injection and proxy: everything left is forwarded to Orthanc with the gateway's Basic Auth header and X-Forwarded-Host/-Proto taken from the public base URL.

3 Stack#

Layer Technology Notes
PACS Orthanc 1.13 (orthancteam/orthanc:26.9.0, pinned) DICOM store, REST API; container memory limit 1 GiB
Index database PostgreSQL 16.15 (pinned) via Orthanc's PostgreSQL index plugin DICOM files stay on a separate volume
DICOMweb Orthanc DICOMweb plugin QIDO-RS and WADO-RS exposed; STOW-RS is not allowed through the gateway
FHIR from DICOM orthanc-java FHIR sample plugin (HAPI FHIR, R5), built from source Mercurial revision pinned in the Dockerfile; Java 11 build, Temurin 11 JRE at runtime
Gateway Node.js 22.23 (Alpine), Express 4, http-proxy-middleware 2, cors one process, no database of its own; npm ci from the lockfile
Report rendering markdown-it + sanitize-html server-side, strict allowlist
UI plain HTML/CSS/vanilla JS, no framework terminal-styled explorer and desk
Viewer Cornerstone3D 5.8.2 (core, tools, dicom-image-loader), bundled with esbuild WADO-RS loader, WASM codecs, decode worker
Tests node:test, no extra dependency 70 tests (gates and limits, RIS layer, Markdown sanitising, desk, identity)
Hosting Docker Compose on Coolify, behind its Traefik proxy auto-deploy on push to main

The Orthanc image is a two-stage build: the first stage clones orthanc-java with Mercurial and builds the C++ JNI plugin, the Java SDK wrapper and the Maven FHIR jar; the second stage adds those artifacts and a JRE to the stock Orthanc image. jsoncpp is compiled into the plugin rather than linked from the system, because the build and runtime images ship different jsoncpp sonames.

The gateway image is also two-stage: one stage installs the Cornerstone devDependencies and builds the viewer bundle; the runtime stage installs production dependencies only and copies the fresh bundle over the committed one.


4 Data model#

There are two data stores, and they are joined on stable identifiers rather than synchronised.

PACS (Orthanc)#

Standard DICOM hierarchy, Patient > Study > Series > Instance, indexed in PostgreSQL. Relevant header values after relabelling:

DICOM attribute Value Example
PatientID (0010,0020) Orthanc patient ID OR-60394
PatientName (0010,0010) as registered at the institute, Family^Given Kaelin^Daniel
AccessionNumber (0008,0050) the RIS order number ORT-2021-791826
StudyInstanceUID (0020,000D) the original UID from the source collection 1.3.6.1.4.1.14519...
StudyDescription the exam catalogue entry

Modalities present: CT, MR, CR, US, plus SEG and SR annotation series from the source collections.

RIS (gateway)#

The RIS is one FHIR R5 Bundle of type collection, produced by the curation pipeline's registration script and uploaded with PUT /ris/registration. The gateway validates it, writes it to a volume (keeping the previous version), and serves it from memory.

Resource Id Key content
Patient the DICOM PatientID (OR-60394) identifiers: Orthanc PID (type MR) and, where on file, a demo AHV number; name, birth date, gender, address, phone; managingOrganization = the institute
Coverage kind: insurance, beneficiary, insurer, member ID
Practitioner e.g. rad-vogt, gp-schmid radiologists, technologists, referring physicians
Organization the institute and the fictional insurers
ServiceRequest (the order) the accession number status completed, intent order, exam code (internal code system), subject, requester (referrer), performer (reading radiologist), occurrenceDateTime, identifiers: accession (type ACSN) and optionally the StudyInstanceUID (urn:dicom:uid, urn:oid:<uid>)
DiagnosticReport (the report) dr-<accession> status final, category RAD, exam code, basedOn exactly one ServiceRequest, subject, study (R5 element) when images exist, resultsInterpreter (the radiologist), issued, conclusion, and the full text as Markdown in presentedForm

Identifier systems:

System Meaning
https://dicom.adrianbernhard.ch/sid/orthanc-pid Orthanc patient ID
https://dicom.adrianbernhard.ch/sid/accession accession number
https://fhir.adrianbernhard.ch/sid/ahv-demo demo AHV number (the same system Erebor uses; 999 prefix, never a real one)
urn:dicom:uid DICOM StudyInstanceUID

How the two sides join:

  • Patient: Patient.id equals DICOM PatientID, so the plugin's ImagingStudy.subject = Patient/OR-60394 resolves to the RIS Patient. One Patient per person, no duplicates by construction. DICOM patients without a registration fall back to the plugin's derived Patient (none at the moment).
  • Study to order: the ServiceRequest carries the StudyInstanceUID; the gateway builds a StudyInstanceUID -> ServiceRequest index and enriches each ImagingStudy with the accession identifier, basedOn and referrer.
  • Report to order and study: validation ties each report to exactly one ServiceRequest, with the same accession, at most one report per order, and a study UID that belongs to that same order.
  • Report-only exams (for example PET-CTs whose images are not held here) are a ServiceRequest plus a DiagnosticReport with no study UID and no ImagingStudy.

Signed reports. "Signed" means a final report with a named resultsInterpreter and an issued time (the generator sets 16:00 Zurich time on the report day). There is no cryptographic signature, no attester, and no preliminary/amended workflow.

Patients without an AHV number (Aebischer, Rüegg) are registered without one on purpose, to exercise the name-plus-birth-date path at the front desk. Some names are registered without umlauts (Ruegg, Kaelin, Lea), also on purpose.


5 Interfaces#

All examples are reads and need no key. OR-60394 is a fictional patient.

sh
BASE=https://dicom.adrianbernhard.ch
STUDY=1.3.6.1.4.1.14519.5.2.1.339753617576638645345666578401058905594

Orthanc REST (allowlisted)#

Endpoint Purpose
GET /statistics counts of patients, studies, series, instances, disk size
GET /{patients,studies,series,instances}[/{id}[/{sub}]] generic Orthanc resources, one level of subresource; bulk downloads (archive, media, file, pdf, attachments) are excluded
POST /tools/find search by DICOM tags (read-only POST, no key)
POST /tools/lookup resolve a DICOM UID to an Orthanc resource ID (read-only POST, no key)
sh
curl -s $BASE/statistics
curl -s $BASE/patients
curl -s -X POST $BASE/tools/find -H 'Content-Type: application/json' \
  -d '{"Level":"Study","Query":{"PatientID":"OR-60394"},"Expand":true}'
curl -s -X POST $BASE/tools/lookup -d "$STUDY"

DICOMweb#

/dicom-web/{studies,series,instances}... is open for reads: QIDO-RS search and WADO-RS retrieve. The plugin's configuration endpoints are not exposed.

sh
curl -s "$BASE/dicom-web/studies?PatientID=OR-60394"                 # QIDO-RS studies
curl -s "$BASE/dicom-web/studies/$STUDY/series"                       # QIDO-RS series
curl -s "$BASE/dicom-web/studies/$STUDY/metadata" -o metadata.json    # WADO-RS metadata

FHIR R5 (/fhir, read-only)#

read and search-type for every type. Search results are a single searchset page by default; _count with a next link (_offset) is honoured. Unknown parameters and modifiers return 400 with an OperationOutcome.

Resource Source Search parameters
Patient RIS store, plugin fallback _id, identifier, family, given, name, birthdate, gender
ImagingStudy FHIR plugin, enriched _id, identifier, subject, patient, based-on
ServiceRequest RIS store _id, identifier, subject, patient, requester
DiagnosticReport RIS store _id, identifier, subject, patient, based-on, study, status, date
Coverage RIS store _id, beneficiary, patient
Practitioner RIS store _id, identifier, name
Organization RIS store _id, name
Endpoint FHIR plugin _id
sh
curl -s $BASE/fhir/metadata
curl -s "$BASE/fhir/Patient?name=kaelin"
curl -s "$BASE/fhir/ImagingStudy?patient=OR-60394"
curl -s "$BASE/fhir/ServiceRequest?patient=OR-60394"
curl -s "$BASE/fhir/DiagnosticReport?patient=OR-60394&_count=1"
curl -s "$BASE/fhir/Coverage?patient=OR-60394"
curl -s "$BASE/fhir/Practitioner?name=vogt"
curl -s $BASE/fhir/Organization
curl -s $BASE/fhir/Endpoint

Search semantics: tokens as system|value, |value, value or system|; strings are case- and accent-insensitive prefix matches with :exact and :contains; dates take eq/ne/lt/gt/le/ge and partial dates; a comma is OR within a parameter, separate parameters are ANDed. _include, _revinclude, _history and versioning are not implemented.

RIS helpers#

Endpoint Purpose
GET /ris/status which registration file is loaded (current or previous), its SHA-256, load time, resource counts
GET /ris/reports/{id} one report rendered for the UI reader: title, dates, accession, radiologist, sanitised HTML, study UID; Cache-Control: no-store
sh
curl -s $BASE/ris/status
curl -s $BASE/ris/reports/dr-ORT-2022-569567

Web pages#

Path What
/ explorer: stats, patient search, exam list, report reader
/viewer/... Cornerstone3D popup viewer (WADO-RS)
/credits imaging sources and citations
/desk front desk (staff page; its API is same-origin only, see section 7)

Writes (not public), all with X-API-Key: POST /instances, PUT /ris/registration, DELETE /{patients,studies,series,instances}/{id}. Nothing else, see section 7.

All read endpoints are rate-limited per client IP (section 7); a 429 carries Retry-After.


6 Standards#

DICOM and DICOMweb#

Images are stored and served as unmodified DICOM objects (only header fields are rewritten during curation). DICOMweb comes from Orthanc's official plugin, so QIDO-RS and WADO-RS behave as in any Orthanc deployment. The viewer loads frames and metadata via WADO-RS. Annotation objects (DICOM SEG and SR) from the source collections are stored as their own series; the viewer keeps them in the series picker but always opens the first series that has pixel data.

Orthanc also listens for DIMSE (C-STORE, C-FIND, C-MOVE) inside its container, but no DICOM port is published, so classic modality and PACS-to-PACS traffic is not possible from outside.

FHIR R5: plugin, facade, or both?#

Both, with the gateway in front:

  • The orthanc-java FHIR plugin (HAPI FHIR, R5) generates Patient, ImagingStudy and Endpoint live from the DICOM data. It is read-only and knows nothing about orders, reports or insurance.
  • The gateway's RIS FHIR layer owns the public /fhir path. It serves the RIS resources from its own store, proxies ImagingStudy and Endpoint from the plugin, enriches them (accession, basedOn, referrer), rewrites the plugin's internal base URL to the public one, and generates its own CapabilityStatement (fhirVersion: 5.0.0) from a registry of served types. The plugin is never reached directly from outside.

The reason for this split: a second HAPI FHIR server for the RIS data would not fit in the host's memory. The facade adds no database and no container.

Validation is structural and referential (ids, references, identifier rules), not full FHIR profile validation.

Why R5 when the hospital is on R4#

The FHIR plugin is built on HAPI FHIR R5, and the institute's FHIR API inherits that version. The mismatch with Erebor (R4) is kept on purpose: real institutions do not upgrade in lockstep, and a portal that aggregates records must cope with more than one FHIR version. The differences show up concretely, for example DiagnosticReport.study (R5) versus imagingStudy (R4). Handling the mismatch is the portal's responsibility (Imladris), not Orthanc's. Moving Orthanc to R4 would mean dropping or forking the plugin.

Mapping to real PACS/RIS workflows#

Real-world concept Here Simplification
IHE Scheduled Workflow (SWF): order placed, procedure scheduled, modality worklist, images acquired, MPPS, storage commitment Orders exist only as completed ServiceRequests, registered after the fact together with the images No order placer/filler messaging (HL7 v2 ORM/OMI), no modality worklist, no MPPS, no scheduling. The data is a finished history, not a live workflow
Accession number linking order, images and report Same accession in the DICOM header, the ServiceRequest identifier, the ImagingStudy identifier (added by the gateway) and the DiagnosticReport identifier Validated at upload, so the links cannot drift
StudyInstanceUID on the order ServiceRequest.identifier with urn:dicom:uid, following the IHE convention
Reporting workflow (draft, preliminary, final, addendum, sign-off) Reports are final on arrival No states, no addenda, no digital signature
IHE XDS-I.b (imaging document sharing: a manifest registered in an XDS registry, images retrieved via WADO-RS/RAD-69) The portal finds studies over FHIR (ImagingStudy, Endpoint) and retrieves them over DICOMweb, closer to IHE MHD/MHD-I or "FHIR + DICOMweb" than to XDS-I No KOS manifests, no XDS registry/repository, no affinity domain. In the Swiss EPD, imaging would be shared through an XDS-I based community; none of that infrastructure is modelled
Patient identification across institutions (IHE PIX/PDQ, the Swiss EPD's EPR-SPID) Front desk matching on the demo AHV number, else name plus birth date See below

AHV versus EPR-SPID. The Swiss electronic patient record (EPD) identifies patients with the EPR-SPID, a dedicated identifier, and explicitly not with the AHV (social security) number. Matching on an AHV number here is a simplification for the demo. The numbers are fake (999 prefix), and some patients have none on file, which forces the fallback path.


7 Access model and privacy#

Gateway rules#

Request Rule
GET / HEAD open, but only for allowlisted paths: /statistics, DICOMweb resources (/dicom-web/{studies,series,instances}...), /fhir/*, /ris/status, /ris/reports/{id}, the generic Orthanc resource paths (no bulk subresources), and static UI files. Everything else is 404, including Orthanc's admin UI, /system and the DICOMweb plugin's configuration endpoints
POST /tools/find, POST /tools/lookup open (Orthanc reads modelled as POST)
any other POST/PUT/PATCH/DELETE requires X-API-Key equal to WRITE_API_KEY, else 401; then only POST /instances, PUT /ris/registration and DELETE /{patients,studies,series,instances}/{id} are allowed, every other write is 403 (no STOW-RS, scripts, resets, modify or anonymize)
writes to /fhir/* 401 without a key; 405 with a key (the FHIR API is read-only, the RIS changes only via PUT /ris/registration)
$operation on /fhir 403 for every method, with or without the key
/desk/api/* same-origin only (Sec-Fetch-Site), preflight OPTIONS refused with 403, 2 kB JSON limit, rate limits

Rate limits (per client IP, fixed one-minute windows, 429 with Retry-After):

Group What Default per minute
api /fhir, /ris, /tools/find, QIDO-RS searches, Orthanc REST, /statistics 120
viewer WADO-RS series/instance metadata, frames, rendered images 3000
heavy whole-study or whole-series retrieves, study-level metadata, an ImagingStudy search without a narrowing parameter 20

Static files are not counted. Requests with the write key or a trusted client key (X-Client-Key, listed in CLIENT_KEYS) are exempt; the portal and the portfolio send one on their server-side calls. The portal's in-app viewer loads frames from the visitor's browser, one request per slice, with no key; the viewer budget was checked locally against the two largest series (461 and 446 slices, 909 requests in 18 seconds, all within the limit). Keys are compared in constant time.

Orthanc's own Basic Auth stays on underneath. The gateway holds the admin credential, sets the Authorization header on every forwarded request (overwriting any client value, so callers cannot supply their own credentials) and removes X-API-Key and X-Client-Key before forwarding. The header is set on the request object in a middleware before the proxy runs, so it is in place before the request body streams, including on large uploads.

CORS is * for the API (other sandbox apps call it from their own origins); the write key, not CORS, is the gate on writes. Retry-After is listed in Access-Control-Expose-Headers, so a browser client such as the portal's viewer can read it on a 429 and back off.

How Imladris uses Orthanc#

  • Server-side (with its client key): QIDO-RS study search (/dicom-web/studies?PatientID=...), and RIS FHIR R5 searches for DiagnosticReport, Patient and Practitioner.
  • From the visitor's browser (the in-app viewer, no key): WADO-RS series metadata and frames, under the viewer rate limit.

Browser hardening#

  • HSTS (max-age=31536000, this host only) and X-Content-Type-Options: nosniff on every response; no X-Powered-By.
  • Content-Security-Policy on every response: own scripts only, no inline script, styles from self and Google Fonts, object-src 'none', base-uri 'none', frame-ancestors 'none'. The viewer's policy adds 'wasm-unsafe-eval' (image codecs) and worker-src 'self' blob:.
  • Report text is rendered server-side in two independent layers: markdown-it with raw HTML disabled and links/images turned off, then sanitize-html with structural tags only and no attributes. The tests feed it a hostile document.

Front desk and identity check#

The front desk is Orthanc's half of the portal's account-linking flow. A patient gets a single-use link code from Imladris; Imladris opens Orthanc's /desk as a popup with that code; staff look it up, pick the matching patient, and redeem it.

  1. Lookup: the gateway calls Imladris's institution API server-to-server with the institution key and receives the claimed identity (name, birth date, AHV). Invalid, expired and used codes all get one generic answer.
  2. Suggestions: registered RIS patients with the same AHV; failing that, patients born that day whose given or family name agrees after normalising. Manual search takes name words, a birth date, an AHV and an Orthanc ID (OR-60394 or or60394), max 20 results. DICOM-only patients without a registration are never offered.
  3. Redeem: the gateway recomputes the identity comparison itself (it does not trust the browser) and sends Imladris the RIS Patient.id as external_patient_id plus the match level and the names of differing fields (never values). A mismatch needs explicit confirmation, else 409.
  4. The page posts a message to the portal's exact origin and closes; opened directly, it says the link is done.

gateway/identity.js (and its test file) is an identical copy of the hospital's version in Erebor's gateway, so both institutions report the same levels and fields:

Level When
match birth date equal, both AHVs present and equal, names equal after normalising
differences birth date equal, nothing contradicts, but a name differs or an AHV is missing on either side
mismatch birth date differs, or both AHVs present and different

Name normalisation: case, whitespace and hyphens ignored, ß = ss, other accents dropped, and umlauts equal under either convention (ä = ae or ä = a), so Rüegg and Ruegg are the same name and Kälin and Kaelin too. Rüegg, who has no AHV on file, therefore links as differences with ahv_missing only.

Desk safeguards: per-IP limits (lookup 10/min, redeem 10/min, search 30/min, then 429 with Retry-After), Referrer-Policy: no-referrer (the URL carries the code), Cache-Control: no-store, Cross-Origin-Opener-Policy: unsafe-none (the popup must keep its opener), and no codes, identities, searches or keys in logs. If any desk setting is missing, /desk says it is not configured and its API answers 503; the rest of the gateway is unaffected.

Privacy#

  • All patients, practitioners, insurers and addresses are fictional; AHV numbers are fake. The images are real research data, de-identified by their publishers and relabelled again here, with no head or face imaging (section 1).
  • Reads are fully open by design. In a real institute none of this (patients, coverage, reports) would be public; here openness is the point of the demo.
  • No real patient data must ever be uploaded. DICOM files and RIS registration data are kept out of version control.

8 Operations#

Deployment. Coolify builds and deploys the Compose stack on every push to main. TLS and routing come from Coolify's Traefik; containers declare their port without a host binding. The first build of the Orthanc image compiles the FHIR plugin from source and takes several minutes.

Persistent state. Three named volumes: the PostgreSQL index, the DICOM files, and the RIS registration (current and previous Bundle).

Environment variables (secrets live in Coolify, never in git; .env.example lists them):

Variable Used by Purpose
POSTGRES_PASSWORD PostgreSQL, Orthanc index database password
ORTHANC_ADMIN_PASSWORD Orthanc, gateway Orthanc Basic Auth; the gateway injects it
WRITE_API_KEY gateway the X-API-Key value for writes
CLIENT_KEYS gateway trusted read-client keys (X-Client-Key), exempt from rate limits
API_RATE_LIMIT, DICOMWEB_RATE_LIMIT, HEAVY_RATE_LIMIT gateway per-IP limits (defaults 120 / 3000 / 20 per minute)
PUBLIC_BASE_URL gateway public origin in FHIR and DICOMweb URLs (defaults to the public URL)
INSTITUTION_KEY_ORTHANC gateway (desk) Orthanc's key at Imladris, 32+ characters
IMLADRIS_URL gateway (desk) Imladris base URL for server-to-server calls
IMLADRIS_ORIGIN gateway (desk) the only postMessage target
ORTHANC_UPSTREAM_URL, ORTHANC_USERNAME, RIS_DATA_DIR, PORT gateway fixed in Compose
DICOM_WEB_PLUGIN_ENABLED, JAVA_PLUGIN_ENABLED, ORTHANC__* Orthanc plugin switches and configuration

Build arguments for the Orthanc image: ORTHANC_JAVA_HG_REV (pinned plugin revision), PLUGIN_VERSION, ORTHANC_IMAGE (pinned base image).

Loading data. Images are uploaded with the write key (POST /instances); the RIS Bundle with PUT /ris/registration. The upload is validated completely before anything changes; an invalid one returns 400 with every error as an OperationOutcome and the live version stays. A valid one is written to a temporary file, the current file is rotated to "previous", and memory is swapped. Re-uploading identical content is a no-op (same SHA-256). On startup the gateway loads the current file, falls back to the previous one, and if both fail serves the plugin-only view; RIS data never stops it from starting.

Nightly reset: none. Unlike the hospital (Erebor), which restores a seed snapshot every night, Orthanc has no reset job. Data persists until someone with the write key changes it. The data set is generated for a fixed anchor date (2026-10-03, the same DEMO_ANCHOR_DATE Imladris is pinned to), so dates do not move. A shared weekly rebuild that rolls all three systems forward in whole weeks is planned, not running.

Memory limits: Orthanc only. Orthanc runs with a 1 GiB container limit. It was sized from local measurements with the full dataset: about 160 MiB idle and about 690 MiB at peak with two viewers loading the two largest series at once plus unfiltered ImagingStudy searches. The embedded JVM sizes its heap from the limit. Production usage has not been measured. The gateway and PostgreSQL have no limit; the design budget for the gateway (under about 60 MiB) is a guideline. No CPU limits.

Orthanc configuration. Everything beyond the Compose environment variables (PostgreSQL index, Basic Auth, plugin switches, Java classpath) is the base image's default, including the DICOMweb plugin's options.

Health and monitoring. PostgreSQL has a Compose health check and Orthanc waits for it. The gateway and Orthanc have none. Monitoring is GET /statistics, GET /ris/status and the explorer's online/offline ping.

Tests. cd gateway && npm test runs 70 tests with Orthanc, the plugin and Imladris faked or mocked. There are no automated tests for the Orthanc image or end-to-end tests in CI.


9 Design decisions and trade-offs#

  1. A FHIR facade in the gateway instead of a second FHIR server. RIS data needed real FHIR resources, but another HAPI server would not fit in memory. The facade serves a validated Bundle from memory and merges the plugin's DICOM-derived resources. Cost: no _include, no history, no transactions, hand-written search semantics, and the gateway must know the plugin's quirks (it matches subject only as a bare id and does not support _id).

  2. IDs aligned across PACS and RIS by construction. Patient.id is the DICOM PatientID and ServiceRequest.id is the accession, so references resolve without a mapping table and duplicates cannot occur. Cost: the RIS cannot renumber anything independently of the images.

  3. Whole-document replace with validation and one-step fallback. The RIS is replaced as a single Bundle, validated first, written atomically, with the previous version kept. Simple and idempotent; dropping a resource from the file removes it from the server. Cost: no partial updates, and a replace is all or nothing.

  4. Orthanc's own auth stays on behind the gateway. Defence in depth: if the network boundary were misconfigured, Orthanc would still refuse unauthenticated requests. Cost: the gateway holds an admin credential and must inject it correctly on every request, streamed uploads included.

  5. Read allowlist instead of read passthrough. Because the gateway injects an admin credential, passing every read through would also open Orthanc's own admin UI. Reads are therefore limited to an explicit list. Cost: every new read use needs an allowlist entry, and two read-only POSTs needed a special case because the write gate keys on HTTP method.

  6. FHIR R5 kept on purpose. It comes for free with the official plugin and gives the sandbox a real cross-version problem to solve in the portal.

  7. Identity rules in one shared file. The identity check is copied byte for byte between the two institutions and run on both the server and the desk page, so the institutions and the UI cannot disagree. Cost: two copies that must be kept in step by hand.

  8. Pinned versions and from-source plugin build. Orthanc, PostgreSQL, the plugin revision and Cornerstone are pinned so a redeploy cannot change behaviour silently. Cost: upgrades are manual, and the plugin build is slow and has many toolchain prerequisites.


10 Known limits and next steps#

Known limits#

Orthanc is a public demo with fictional data. Most limits below follow from that scope: a real institute would need them, a sandbox meant to be explored does not.

  • Open reads. All registry data is readable without authentication, including addresses, phone numbers and insurance member IDs (all fictional). There is no user authentication, no audit trail and no consent model; openness is the point of the demo.
  • One write key. All writers share one key; there are no per-client write keys, roles or rotation mechanism. Only the curation scripts write.
  • Front desk without staff login. Anyone can open /desk; without a valid link code it can only search the fictional registry. A staff login was left out of the demo scope.
  • No DIMSE from outside, and no modality worklist, MPPS or HL7 v2: the data is a finished history, not a live workflow.
  • Reports are final only, with no signature, addenda or amendment history.
  • Exam codes use an internal code system; there is no LOINC or RadLex mapping.
  • FHIR has no _include/_revinclude, no _history, no conditional or transactional writes and no profile validation. An unfiltered ImagingStudy search is slow (the full list comes from the plugin, about 0.8 MB and several seconds), which is why it falls in the heavy rate-limit group.
  • Rate limits are per IP and in memory: visitors behind one NAT share a budget, and a gateway restart resets the counters.
  • Resources: only Orthanc has a memory limit, and Orthanc and the gateway have no health checks.
  • Dependencies: http-proxy-middleware 2 has a known advisory in a transitive dependency; the fix needs the upgrade to v3.
  • Viewer codecs: the current studies are uncompressed, so the viewer's WASM codecs and their CSP allowance have not been exercised by real data.
  • No-head-imaging rule is enforced in the curation pipeline, not at upload.

Next steps#

  • Upgrade http-proxy-middleware to v3 and retest every proxied path.
  • Add health checks, and confirm the Orthanc memory limit against production usage.
  • Map the exam catalogue to LOINC/RadLex.
  • Optionally model the ordering side (an order from Erebor to Orthanc), and a report status workflow.

11 Try it#

  1. Browse: open https://dicom.adrianbernhard.ch, type Kaelin in the name field (or OR-60394 in the ID field), open the patient, click read on an exam for the report and view for the images.
  2. Query the RIS:
    sh
    curl -s "https://dicom.adrianbernhard.ch/fhir/Patient?name=kaelin"
    curl -s "https://dicom.adrianbernhard.ch/fhir/DiagnosticReport?patient=OR-60394&_count=1"
    
  3. Query the images:
    sh
    curl -s "https://dicom.adrianbernhard.ch/dicom-web/studies?PatientID=OR-60394"
    
  4. See a write refused:
    sh
    curl -s -i -X POST https://dicom.adrianbernhard.ch/instances
    # HTTP/1.1 401 ... {"error":"Missing or invalid X-API-Key header"}
    
  5. Run the tests locally:
    sh
    cd gateway && npm install && npm test
    
  6. Run the stack locally: copy .env.example to .env, fill in the passwords and the write key, docker compose up -d (the first build compiles the FHIR plugin), then PUT a registration Bundle to /ris/registration with the write key. The desk additionally needs the three Imladris settings.
  7. Link an account: in the patient portal (portal.adrianbernhard.ch), linking an Orthanc record opens this institute's front desk as a popup.