Build a local DICOM test lab with Docker
- A Docker Compose file with Orthanc as PACS and DCMTK as client builds a local DICOM test lab.
- C-ECHO verifies association connectivity before you attempt a C-STORE transfer.
- Orthanc allows open C-STORE by default but restricts C-FIND and C-MOVE unless explicitly enabled.
- findscu requires the -S flag for Study Root queries or Orthanc may reject the presentation context.
- Local Docker labs do not reproduce real hospital network latency, restrictive transfer syntaxes, or multi-tenant traffic.
You do not need access to a hospital network to test DICOM software. With one docker-compose.yml file, you can run a local Picture Archiving and Communication System (PACS) and a test client on your laptop. You can establish associations, send real imaging studies, and inspect headers in 5 minutes.
Testing against live clinical systems is slow and risky. Clinical engineering teams take weeks to approve test Application Entity (AE) titles and firewall rules. When a hospital transfer fails, identifying whether the root cause was a firewall, a wrong AE title, or bad attributes is difficult.
A local Docker environment eliminates these unknowns. It gives you an isolated, repeatable target where you control both the sender and the receiver.
This guide walks you through building a local test lab using Orthanc as the PACS server and DCMTK as the client toolkit. This setup uses Docker Compose v2.34, Orthanc 1.12.11 (via the official orthancteam/orthanc:latest image), and DCMTK 3.6.7 on Debian 12.
Why you need a Docker DICOM test lab before touching clinical networks
Connecting directly to a hospital PACS during early development is a bad idea. Hospital systems enforce strict security boundaries. They require signed agreements, approved IP addresses, and scheduled maintenance windows. If your application sends malformed attributes or drops an association unexpectedly, you waste time coordinating with hospital IT administrators.
A local Docker DICOM test lab gives you three clear advantages. First, you get immediate feedback. You can launch the lab, transmit 100 instances, and inspect the logs in seconds.
Second, you can test failure modes safely. You can simulate connection resets, mismatched transfer syntaxes, and rejected associations without affecting patient workflows.
Third, you can reset the entire environment with a single command. If you populate the archive with bad test data, you can wipe the volume and start clean.
We use Orthanc for the PACS server and DCMTK for the client. Orthanc is lightweight, open source, and includes both standard DICOM network interfaces and a clean HTTP REST API. DCMTK provides battle-tested command-line utilities like echoscu, storescu, and findscu. Together, they let you exercise every common DICOM operation locally.
The single Docker Compose file for Orthanc and DCMTK
You can define the entire test lab in a single docker-compose.yml file. This configuration sets up two services on a shared private bridge network. The orthanc service acts as the Service Class Provider (SCP), listening for inbound DICOM connections. The dcmtk service acts as the Service Class User (SCU), providing client binaries to initiate transfers.
Between installing DCMTK directly on your host or running it in a companion container, we prefer the companion container in Docker Compose. You give up the convenience of typing commands without docker compose exec. In exchange, your entire team runs the exact same tool versions without local package installation headaches.
Here is the complete docker-compose.yml file:
services:
orthanc:
image: orthancteam/orthanc:latest
container_name: orthanc
ports:
- "4242:4242" # DICOM C-STORE and C-ECHO port
- "8042:8042" # Web UI and REST API
environment:
ORTHANC__NAME: "LocalTestPACS"
ORTHANC__DICOM_AET: "ORTHANC"
# Explicit user credentials are required in Orthanc 1.13.0 and newer
ORTHANC__REGISTERED_USERS: '{"demo": "demo"}'
# Allow queries from any test AE title without pre-registration
ORTHANC__DICOM_ALWAYS_ALLOW_FIND: "true"
ORTHANC__DICOM_ALWAYS_ALLOW_MOVE: "true"
volumes:
- orthanc-storage:/var/lib/orthanc/db
dcmtk:
build:
context: .
dockerfile_inline: |
FROM debian:12-slim
RUN apt-get update && apt-get install -y --no-install-recommends dcmtk && rm -rf /var/lib/apt/lists/*
WORKDIR /data
container_name: dcmtk
volumes:
- ./data:/data
command: ["sleep", "infinity"]
volumes:
orthanc-storage:
Create a directory named data next to this file. Place any .dcm test files you want to transmit inside that data folder. Docker mounts this folder into /data inside the dcmtk container.
Notice the port mappings. Port 4242 handles DICOM network communications over TCP. Port 8042 serves Orthanc’s web interface and REST API.
If you have DCMTK installed directly on your host machine, you can point your local tools to localhost:4242. If you prefer keeping your host clean, you can run all commands directly inside the dcmtk container.
Starting the test lab and verifying container health
To start both containers in the background, run:
docker compose up -d
Docker downloads the Orthanc image, builds the lightweight DCMTK client container, and starts both services. You can verify that both containers are running with:
docker compose ps
Before sending image files, verify that the DICOM network layer is operational. In DICOM, you test basic connectivity with a C-ECHO request. This operation works like a network ping, but operates at the DICOM application protocol layer.
Run echoscu from inside the dcmtk container:
docker compose exec dcmtk echoscu -v -aec ORTHANC orthanc 4242
The command requests an association with the called AE title ORTHANC on container host orthanc at port 4242. You will see output like this:
I: Requesting Association
I: Association Accepted (Max Send PDV: 16372)
I: Sending Echo Request (MsgID 1)
I: Received Echo Response (Success)
I: Releasing Association
This exchange confirms three critical points. The TCP connection opened successfully, and Orthanc accepted the association negotiation. Orthanc also returned a success status for the verification Service Object Pair (SOP) class.
For more detail on how association handshakes work, read our guide on DICOM C-ECHO verification and connectivity testing.
Sending a test study with storescu and dcmsend
Once C-ECHO succeeds, you can transmit a test DICOM file using C-STORE. The classic DCMTK command for sending files is storescu.
Assuming you copied a file named sample.dcm into your ./data directory, run:
docker compose exec dcmtk storescu -v -aec ORTHANC orthanc 4242 /data/sample.dcm
The terminal displays the transfer progress:
I: checking input files ...
I: Requesting Association
I: Association Accepted (Max Send PDV: 16372)
I: Sending file: /data/sample.dcm
I: Sending Store Request (MsgID 1, SC)
XMIT: .
I: Received Store Response (Success)
I: Releasing Association
If you need to send an entire directory of slices, use dcmsend instead. While storescu sends files individually, dcmsend scans subdirectories, configures presentation contexts automatically, and prints a final transmission report. Run:
docker compose exec dcmtk dcmsend -v -aec ORTHANC orthanc 4242 /data/
dcmsend reports how many associations it opened, how many instances succeeded, and whether any transfers failed. To learn about the differences between individual tool options, see our reference on DCMTK commands for developers.
When building an integration for cloud systems, keep in mind how DICOM C-STORE compares with DICOMweb STOW-RS. You can also follow our documentation on connecting a sender to see how sending entities configure remote destinations.
How do you verify the test study reached the PACS?
Sending bytes over a socket is only half the job. You also need to verify that the receiving PACS parsed, indexed, and stored the study correctly.
Orthanc gives you two independent ways to inspect stored data: a web interface and an HTTP REST API.
Open your browser and navigate to http://localhost:8042. When prompted, log in with username demo and password demo. Orthanc displays its web interface, called Orthanc Explorer.
Click All studies to view the study you just sent. You can inspect patient demographics, examine series metadata, and preview individual image slices directly in your browser.
If you are writing automated tests, query Orthanc’s REST API using curl:
curl -s -u demo:demo http://localhost:8042/studies
Orthanc returns a JSON array containing the internal identifiers of all stored studies:
[
"6664d494-9a85b1a5-c96d925e-3ca129a1-33b5cb55"
]
To fetch detailed metadata for a specific study, append its identifier to the URL:
curl -s -u demo:demo http://localhost:8042/studies/6664d494-9a85b1a5-c96d925e-3ca129a1-33b5cb55
The response includes patient identifiers, Study Instance UIDs, series listings, and storage statistics. If you need to integrate DICOM delivery notifications into your backend, see our documentation on receiving deliveries.
Testing C-FIND queries and the modal security trap
Many developers assume that if C-STORE works, C-FIND queries will work automatically. In real clinical PACS and in Orthanc, that assumption fails.
In default configurations, Orthanc permits any calling AE title to store images. This setting corresponds to DicomAlwaysAllowStore: true. However, Orthanc restricts query and retrieve operations (C-FIND and C-MOVE). By default, Orthanc rejects query requests from unknown AE titles to prevent unauthorized enumeration of patient records.
If you omit ORTHANC__DICOM_ALWAYS_ALLOW_FIND: "true" from your environment variables, running findscu produces a silent abort:
E: 0006:0317 Peer aborted Association (or never connected)
Checking Orthanc’s container logs reveals the true cause:
W: DICOM authorization rejected for AET FINDSCU: This AET is not listed in configuration option "DicomModalities"
With ORTHANC__DICOM_ALWAYS_ALLOW_FIND: "true" enabled in our Docker Compose file, Orthanc accepts queries from any AE title.
To execute a study-level C-FIND query, run:
docker compose exec dcmtk findscu -v -S -aec ORTHANC orthanc 4242 \
-k 0008,0052=STUDY \
-k 0010,0020 \
-k 0020,000D
Notice the -S flag. This flag tells findscu to use the Study Root query model. If you omit -S, findscu proposes the Patient Root model by default, and Orthanc may reject the presentation context. The -k flags specify the query retrieve level and the attributes you want Orthanc to return.
The terminal output shows the matched dataset:
I: Find Response: 1 (Pending)
I: (0008,0052) CS [STUDY]
I: (0010,0020) LO [SYNTHETIC-001]
I: (0020,000d) UI [1.2.826.0.1.3680043.10.54321.2]
I: Received Final Find Response (Success)
Understanding how AE titles govern permissions is essential for real hospital deployments. For background on naming conventions, read our guide on what a DICOM Application Entity title represents.
Common failures and how to fix them
When running a local DICOM lab, you will encounter three common failure patterns.
First, Orthanc exits immediately on startup with exit code 253. The container logs state that remote access is enabled but no user is declared. Starting with Orthanc 1.13.0, the container requires explicit credentials when listening on exposed interfaces. You must set either ORTHANC__REGISTERED_USERS with a valid JSON string or define ORTHANC_PASSWORD in your Compose file.
Second, your client reports Association Rejected: Calling AE Title Not Recognized. While our Compose setup enables open store permissions, production PACS systems check calling AE titles strictly. Always confirm that your client’s -aet parameter matches the title configured on the receiving server.
Third, findscu returns E: No Acceptable Presentation Contexts. This error occurs when the client and server cannot agree on an Information Model. Ensure you specify -S for Study Root queries, or confirm that the server supports Patient Root negotiation.
Where a local Docker test lab falls short
A local Docker environment is an essential first step, but it has clear limitations.
First, Docker bridge networks do not simulate real hospital network conditions. On your laptop, round-trip latency is under 1 millisecond and packet loss is zero. Clinical hospital networks often traverse site-to-site VPNs, complex firewalls, and saturated outbound gateways. High latency changes how association negotiation and multi-slice transfers behave under load.
Second, Orthanc accepts almost all common DICOM transfer syntaxes and SOP classes without complaint. Proprietary hospital PACS and legacy scanner workstations are far more restrictive. Some archives only accept Explicit VR Little Endian, while others fail when receiving compressed JPEG 2000 or JPEG-LS transfer syntaxes.
Third, a local lab tests point-to-point connections, not multi-tenant production traffic. A production gateway must handle hundreds of concurrent hospital senders, manage mutual TLS certificates, and route transfers without buffering gigabytes of data in memory.
Use your local Docker lab to debug DICOM datasets, verify tag hierarchies, and validate tool flags. When you move to staging, test against clinical endpoints that reproduce realistic network conditions.
Dicomly builds infrastructure for healthcare software teams that receive DICOM studies from hospitals. Why we built Dicomly →