OHIF Viewer v3.12.17 Docker Install Guide

Deploy OHIF Viewer v3.12.17 tonight with Docker – no Node, no Yarn, no monorepo fight. As of September 2026, that tag is the stable line on Docker Hub. Browser open, studies load, done.

OHIF (Open Health Imaging Foundation) is an MIT-licensed zero-footprint web DICOM viewer: React PWA, Cornerstone3D, DICOMweb-ready. Source lives at GitHub OHIF/Viewers; production path here is the official ohif/app image plus a config you control.

Opening the demo study list on first boot feels like success. It isn’t – not yet. You’re still on baked sample roots until the mount path is right. That false comfort trips more first installs than bad pull commands.

What you need on the host

Docker Engine or Docker Desktop only. Host Node/Yarn is for source builds; skip it for Hub images. Give the machine enough free RAM if you also spin the Nginx-Orthanc recipe (that stack is heavier than the viewer alone). Browser: recent Chrome, Firefox, Edge, or Safari. Your archive must expose DICOMweb QIDO/WADO roots the browser can reach (same-origin via proxy, or CORS-ready).

Building from source still wants the full monorepo toolchain plus Docker – see the Docker deployment docs. This guide stays on Hub tags.

Where to get the image

Skip random forks.

• Docker Hub ohif/app – latest resolves to v3.12.17 (~116 MB compressed), amd64/arm64; latest-beta tracks v3.14.0-beta.x
• Release tags: github.com/OHIF/Viewers/releases (v3.12.17 marked Latest as of 10 Sep 2026; security dependency patches)
• Docs hub: docs.ohif.org

Pin ohif/app:v3.12.17 in compose. Silent latest bumps after a CVE patch are fine; surprise feature drift is not. Feature line v3.13.0 (July 2026) brings Smart Scrollbar, a new Study List, UI-next themes, and Cornerstone 5.0 on ohif.org release notes – while Hub latest still tracked the 3.12.17 patch line when this was written. Check tags before you assume.

Install with Docker

# 1. Pull pinned stable (v3.12.17 as of Sep 2026)
docker pull ohif/app:v3.12.17

# 2. Detached; host 3000 → nginx 80
docker run -d 
 -p 3000:80 
 --name ohif-viewer 
 --restart unless-stopped 
 ohif/app:v3.12.17

# 3. Sanity
docker ps --filter name=ohif-viewer
docker logs ohif-viewer --tail 30

Open http://localhost:3000. Study list from the image demo data source is expected until you override config.

Pin the tag. Period. Reproducible deploys after CVE-driven patches beat floating latest or beta drift.

Minimum app-config.js

Point at your archive. Shape from the configuration docs:

window.config = {
 routerBasename: '/',
 showStudyList: true,
 defaultDataSourceName: 'dicomweb',
 dataSources: [
 {
 namespace: '@ohif/extension-default.dataSourcesModule.dicomweb',
 sourceName: 'dicomweb',
 configuration: {
 friendlyName: 'Local PACS',
 name: 'orthanc',
 wadoUriRoot: 'http://YOUR_PACS/dicom-web',
 qidoRoot: 'http://YOUR_PACS/dicom-web',
 wadoRoot: 'http://YOUR_PACS/dicom-web',
 qidoSupportsIncludeField: false,
 imageRendering: 'wadors',
 thumbnailRendering: 'wadors',
 enableStudyLazyLoad: true,
 supportsFuzzyMatching: false,
 supportsWildcard: true
 }
 }
 ]
};

Turns out the mount target is picky. File → exact path, not a folder:

docker rm -f ohif-viewer

docker run -d 
 -p 3000:80 
 --name ohif-viewer 
 -v /absolute/path/app-config.js:/usr/share/nginx/html/app-config.js:ro 
 ohif/app:v3.12.17

Env injection is contents, not a path string (docs.ohif.org Docker deployment):

docker run -d -p 3000:80 --name ohif-viewer 
 -e APP_CONFIG="$(cat /absolute/path/app-config.js)" 
 ohif/app:v3.12.17

Strip // line comments before the env method – they can break client serving. Wrong host path or a directory mount leaves the baked demo roots in place; people report localhost:3000 still looking like viewer.ohif.org-style studies (same class of failure as GitHub issue discussions around ignored Docker config).

The catch is memory, not YAML, when you want Orthanc beside the viewer:

git clone https://github.com/OHIF/Viewers.git
cd Viewers/platform/app/.recipes/Nginx-Orthanc
docker-compose up --build

Viewer at http://127.0.0.1, Orthanc UI at /pacs, DIMSE 4242. Exit code 137 during build or Orthanc startup means Docker OOM – raise Docker Desktop memory, retry. Do not put this recipe on the public internet without auth.

Verify

1. docker ps – ohif-viewer running.
2. Browser – OHIF chrome at http://localhost:3000.
3. After mount – DevTools Network shows QIDO against your roots (rs / dicom-web).
4. Known StudyInstanceUID – WADO-RS tiles stream.
5. Optional – docker exec ohif-viewer ls /usr/share/nginx/html/app-config.js proves the file mount.

Install errors that actually show up

Still only demo studies. Volume target must be /usr/share/nginx/html/app-config.js. Synology and plain Docker reports often mount the wrong path or a directory; Docker happily creates a directory bind and never overrides the script.

Compose exit 137. OOM. Bump Docker memory (Desktop → Advanced), then docker-compose up --build again. Nginx + Image Archive docs list this first.

Port busy.docker rm -f ohif-viewer or -p 3001:80.

CVE-2026-12473 (patch floor). On ≤3.12.0, authenticated setups using dicomwebproxy / dicomjson could leak OIDC bearer tokens via crafted ?url= fetches – CVSS 8.2 per CISA ICSMA-26-176-02. Fix landed in 3.12.2 (18 May 2026). You are on 3.12.17. If those data sources stay under auth, set dangerouslyAllowedOriginsForAuthenticatedEnvironments to an explicit allowlist. Plain DICOMweb sources were not impacted. Advisory: CISA ICSMA-26-176-02.

CORS / mixed content. Put nginx (or the recipe proxy) in front so viewer and archive share a host, or fix archive CORS.

Source build pain on ARM/yarn. Use Hub multi-arch images. Monorepo native modules are a different job than this deploy path.

Upgrade and uninstall

docker pull ohif/app:v3.12.17
docker stop ohif-viewer && docker rm ohif-viewer
# same docker run with your -v / -e flags

Keep app-config.js on the host so upgrades do not wipe data sources. Jumping 3.12 → 3.13: read worklist migration notes on ohif.org first.

docker stop ohif-viewer
docker rm ohif-viewer
docker rmi ohif/app:v3.12.17
# Orthanc recipe: docker-compose down -v from the recipe directory

Static PWA hosting behind nginx or S3 is fine once the config is locked. Docker still wins when you are iterating data-source roots and refuse a full rebuild each try.

One open question before PHI: who signs off that this self-hosted stack meets your org’s imaging and identity controls? The MIT license answers cost. It does not answer governance.

FAQ

Is OHIF Viewer free for clinical use?

MIT-licensed – free to run. Clearance and PHI policy are your compliance team’s call, not the container tag’s.

Docker or build from source?

Hub image for standard deploys. Build from source when you ship private extensions, modes, or hanging protocols – clone OHIF/Viewers, set config at build time, use the repo Dockerfile. Example: custom segmentation mode baked into the bundle. “Point at our Orthanc” only needs a volume-mounted app-config.js on ohif/app:v3.12.17.

Why is the study list empty after a “correct” mount?

Open DevTools → Network, run a search, read the failing call. Wrong qidoRoot/wadoRoot (missing archive path segments) and CORS preflight failures are the usual killers – QIDO never returns JSON. Same-origin proxy (Nginx-Orthanc pattern) kills most CORS noise. And confirm the bind is a file on app-config.js: a directory mount fails quietly and leaves demo roots. Filters in the UI can also hide real studies; widen them after the network tab looks clean.

Next: three-line pull/run, open localhost:3000, replace demo roots with the volume mount above.