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):
- Security headers (CSP, HSTS,
nosniff) are set on every response. - Front desk (
/desk,/desk/api/*) is handled first and never reaches Orthanc. - CORS (
*) and static files (public/: explorer, credits, viewer bundle). - Read allowlist: a
GET/HEADnot matched by a static file must be on an explicit allowlist, otherwise 404. This is what keeps Orthanc's own admin UI (/app/...) unreachable. - No FHIR operations: any
$operationon/fhiris 403. - Rate limits per client IP, in three groups (section 7).
- Write gate:
POST/PUT/PATCH/DELETEneedX-API-Key, except two read-only POSTs (/tools/find,/tools/lookup); with the key, only a short list of writes is allowed (section 7). - RIS router owns
/fhir/*and/ris/*. - Auth injection and proxy: everything left is forwarded to Orthanc with the
gateway's Basic Auth header and
X-Forwarded-Host/-Prototaken 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.idequals DICOM PatientID, so the plugin'sImagingStudy.subject = Patient/OR-60394resolves 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 -> ServiceRequestindex and enriches each ImagingStudy with the accession identifier,basedOnandreferrer. - 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
studyUID 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.
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) |
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.
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 |
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 |
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,ImagingStudyandEndpointlive 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
/fhirpath. It serves the RIS resources from its own store, proxiesImagingStudyandEndpointfrom the plugin, enriches them (accession,basedOn,referrer), rewrites the plugin's internal base URL to the public one, and generates its ownCapabilityStatement(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 forDiagnosticReport,PatientandPractitioner. - 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) andX-Content-Type-Options: nosniffon every response; noX-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) andworker-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.
- 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.
- 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-60394oror60394), max 20 results. DICOM-only patients without a registration are never offered. - Redeem: the gateway recomputes the identity comparison itself (it does not
trust the browser) and sends Imladris the RIS
Patient.idasexternal_patient_idplus the match level and the names of differing fields (never values). Amismatchneeds explicit confirmation, else 409. - 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#
-
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 matchessubjectonly as a bare id and does not support_id). -
IDs aligned across PACS and RIS by construction.
Patient.idis the DICOM PatientID andServiceRequest.idis the accession, so references resolve without a mapping table and duplicates cannot occur. Cost: the RIS cannot renumber anything independently of the images. -
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.
-
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.
-
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.
-
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.
-
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.
-
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
finalonly, 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 unfilteredImagingStudysearch 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-middleware2 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-middlewareto 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#
- Browse: open https://dicom.adrianbernhard.ch, type
Kaelinin the name field (orOR-60394in the ID field), open the patient, click read on an exam for the report and view for the images. - 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" - Query the images:sh
curl -s "https://dicom.adrianbernhard.ch/dicom-web/studies?PatientID=OR-60394" - 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"} - Run the tests locally:sh
cd gateway && npm install && npm test - Run the stack locally: copy
.env.exampleto.env, fill in the passwords and the write key,docker compose up -d(the first build compiles the FHIR plugin), thenPUTa registration Bundle to/ris/registrationwith the write key. The desk additionally needs the three Imladris settings. - Link an account: in the patient portal (portal.adrianbernhard.ch), linking an Orthanc record opens this institute's front desk as a popup.