dcm4chee-arc-light 5.35.2

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick dcm4chee-arc-light 5.35.2 on Ubuntu 24.04 as the software version, select your Region, and choose Launch through EC2.

Choose m5.large (or larger), your key pair, a security group as described above, and a subnet. Under Configure storage, you see two volumes: the root volume and the 32 GiB data volume for the archive. Raise the data volume's size now if you already know you need more.

To launch with the AWS CLI instead, replace the values in angle brackets:

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=dcm4chee}]'

Version SSH user

dcm4chee-arc-light 5.35.2 on Ubuntu 24.04 ubuntu

ssh -i <your-key.pem> ubuntu@<public-ip>

First boot generates every password, key and certificate, creates the LDAP and PostgreSQL databases, and starts the archive. This takes about a minute:

systemctl is-active docker sac-dcm4chee-netguard dcm4chee-arc-firstboot dcm4chee-arc nginx

active active active active active

The three containers run under Docker Compose:

sudo docker compose -f /opt/dcm4chee/compose.yaml ps --format '{{.Service}} {{.State}}'

arc running db running ldap running

Only SSH (22) and nginx (80, 443) listen on the network. The archive's HTTP (8080) and DICOM (11112) ports are on loopback only, and the other two are Ubuntu's local DNS resolver:

sudo ss -lntp | awk 'NR>1 {print $4}' | sort -u

0.0.0.0:22 0.0.0.0:443 0.0.0.0:80 127.0.0.1:11112 127.0.0.1:8080 127.0.0.53%lo:53 127.0.0.54:53 [::]:22 [::]:443 [::]:80

If nginx is not active, first boot has not finished, or it failed, in which case nginx stays down. Check systemctl status dcm4chee-arc-firstboot and journalctl -u dcm4chee-arc-firstboot.

sudo cat /root/dcm4chee-arc-light-credentials.txt

The file is readable by root only:

# dcm4chee-arc-light 5.35.2 on Ubuntu 24.04 (sac). Generated ON THIS INSTANCE at first boot. DCM4CHEE_URL=https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/dcm4chee-arc/ui2/ DCM4CHEE_WEB_USERNAME=dcm4chee DCM4CHEE_UI_PASSWORD=<DCM4CHEE_UI_PASSWORD> DICOMWEB_BASE=/dcm4chee-arc/aets/DCM4CHEE/rs DICOM_AE_TITLE=DCM4CHEE DICOM_PORT=11112 (127.0.0.1 only until you run:
sudo dcm4chee-dimse allow <AET> && sudo dcm4chee-dimse open)

The URL uses the instance's public DNS name from EC2 instance metadata. The certificate also names the public and private IP addresses. To use your own DNS name, see Step 9.

The built-in self-test checks the whole chain from the command line. On an empty archive, it stores the synthetic test study over DICOMweb, queries and retrieves it, and deletes that study again by its UID. When the archive already holds other studies, the self-test writes nothing and runs only the read-only checks:

sudo dcm4chee-selftest

SELFTEST-OK + STOW/QIDO/WADO round trip (phantom stored, then rejected and deleted by its StudyInstanceUID) https 301 + /healthz + 401 without/with a wrong/default password on every path + archive STARTED + 403 cross-site/none/foreign-Origin on a guarded route + 403 cross-origin POST + 444 unknown host + LDAP/PostgreSQL upstream defaults refused + no host-side WildFly management + DIMSE on 127.0.0.1 + IMDS blocked in arc/ldap/db

Open the DCM4CHEE_URL in your browser. The certificate is self-signed, so your browser asks you to confirm it the first time. Before you accept it, compare the fingerprint that your browser shows with the one on the instance (or install your own certificate, Step 9):

sudo openssl x509 -in /etc/ssl/dcm4chee/dcm4chee.crt -noout -fingerprint -sha256

Your browser then asks for a user name and password. Enter dcm4chee and the DCM4CHEE_UI_PASSWORD from Step 4. The UI2 interface opens on the Studies page, where you can search studies by patient, date, modality and more.

The same user name and password protect the REST API and DICOMweb. From the instance itself, use curl to store the synthetic test study with STOW-RS and to query it back with QIDO-RS. The password goes into a private curl config file, never onto the command line, and the file is removed at the end:

F=/root/dcm4chee-arc-light-credentials.txt
H=$(sudo sed -n 's#^DCM4CHEE_URL=https://\([^/]*\)/.*#\1#p' $F) ( umask 077; printf 'user = "dcm4chee:%s"\n' "$(sudo sed -n 's/^DCM4CHEE_UI_PASSWORD=//p' $F)" > ~/.dcm4chee-curl ) B=sacGuide; rm -f /tmp/stow.body for f in /usr/share/dcm4chee-arc-light/sample-dicom/*.dcm; do printf -- '--%s\r\nContent-Type: application/dicom\r\n\r\n' $B >> /tmp/stow.body; cat "$f" >> /tmp/stow.body; printf '\r\n' >> /tmp/stow.body; done printf -- '--%s--\r\n' $B >> /tmp/stow.body curl -s -K ~/.dcm4chee-curl --resolve "$H:443:127.0.0.1" --cacert /etc/ssl/dcm4chee/dcm4chee.crt -o /dev/null -w 'STOW-RS -> HTTP %{http_code}\n' \
  -X POST -H "Content-Type: multipart/related; type=\"application/dicom\"; boundary=$B" --data-binary @/tmp/stow.body \
  "https://$H/dcm4chee-arc/aets/DCM4CHEE/rs/studies" curl -s -K ~/.dcm4chee-curl --resolve "$H:443:127.0.0.1" --cacert /etc/ssl/dcm4chee/dcm4chee.crt \
  "https://$H/dcm4chee-arc/aets/DCM4CHEE/rs/studies?PatientID=SAC-PHANTOM-001" | grep -o '"PHANTOM^SAC"' | head -1 rm -f /tmp/stow.body ~/.dcm4chee-curl

STOW-RS -> HTTP 200 "PHANTOM^SAC"

In the web interface, open the Studies page and choose DCM4CHEE as the Web App Service. Enter SAC-PHANTOM-001 as the Patient Identifier and choose SUBMIT. Expand the study with its arrow to see its two series.

DICOMweb clients and viewers point at https://<your-host>/dcm4chee-arc/aets/DCM4CHEE/rs with HTTP Basic authentication. The routes that make the archive contact other systems (/dcm4chee-arc/aets/<AET>/dimse/..., /diff/..., /pdq/..., /xroad/..., /impax/..., /token2/..., /host/...) are refused with 403 unless the request carries Sec-Fetch-Site: same-origin. Browsers send this header on the UI's own requests, and a script that calls these routes must send the header itself. A request that changes data is refused with 403 when it carries another web site's Origin.

When you are done with the test study, delete it in the UI (the study's menu offers reject and then delete), or use curl as above:POST .../rs/studies/<study-uid>/reject/113039%5EDCM, then DELETE https://$H/dcm4chee-arc/aets/IOCM_REGULAR_USE/rs/studies/<study-uid>.

To replace the web password with a new random one, run the following command. The new password is written to the credentials file, and the old one stops working at once:

sudo dcm4chee-set-password

Your browser may keep offering the old password until you close it.

DICOM DIMSE (C-STORE, C-FIND, C-MOVE, C-GET to AE title DCM4CHEE on port 11112) has no password. The archive also answers on the same port as several other AE titles (WORKLIST, AS_RECEIVED and the IOCM_* titles used for rejection workflows).

Before you publish the port, tell the archive which calling AE titles it may accept. dcm4chee-dimse allow sets that allowlist on every network AE of the archive. Then open the port, and allow it in the security group only from your modalities' addresses:

sudo dcm4chee-dimse status

DIMSE bind address: 127.0.0.1 (port 11112, AE title DCM4CHEE) listening: 127.0.0.1:11112 AE AS_RECEIVED (installed TRUE): accepted calling AE titles: ANY (no allowlist) AE DCM4CHEE (installed TRUE): accepted calling AE titles: ANY (no allowlist) AE IOCM_EXPIRED (installed TRUE): accepted calling AE titles: ANY (no allowlist) ... AE WORKLIST (installed TRUE): accepted calling AE titles: ANY (no allowlist) allowlist: NOT set on every installed AE (open is refused)

sudo dcm4chee-dimse allow <MODALITY_AET> <ANOTHER_AET>
sudo dcm4chee-dimse open

open refuses unless every installed AE carries the allowlist. It restarts the archive container with port 11112 published on all interfaces, which takes about a minute. Docker-published ports are not filtered by ufw, so the security group is what limits who can connect. Add an inbound rule for TCP 11112 from your modalities only.

An AE title is not authentication, because anyone who can reach the port can claim one. The allowlist also does not limit which studies an accepted AE sees, so keep port 11112 private to your imaging network. In the UI, you can additionally register each modality as a device and switch on Validate Calling AE Hostname for the DCM4CHEE AE.

Every start of the archive checks this again. If DIMSE is open but any installed AE has lost its allowlist (for example after you add an AE in the UI), DIMSE is closed back to localhost. A quick DICOM C-ECHO from the instance shows the allowlist at work. It returns ACCEPTED for a listed AE title and REJECTED for any other. Add a called AE title as a third argument to test another AE:

sudo dcm4chee-dimse echo <MODALITY_AET>

To take DIMSE back to localhost, run sudo dcm4chee-dimse close. To test with your own tools, use DCMTK's echoscu/storescu (storescu -aet <MODALITY_AET> -aec DCM4CHEE <host> 11112 <files>) or upstream's dcm4che/dcm4che-tools image. Both work.

Point a DNS record at the instance (an Elastic IP keeps the address across stop and start), then tell the archive its name. This creates a new self-signed certificate for that name, updates the nginx host rule and the cross-site guards, and keeps the name across reboots:

sudo dcm4chee-set-hostname pacs.example.com

To use a certificate from a public authority instead, replace /etc/ssl/dcm4chee/dcm4chee.crt (full chain) and /etc/ssl/dcm4chee/dcm4chee.key (mode 0600, owned by root) with your own, then run sudo systemctl reload nginx. Running dcm4chee-set-hostname again later replaces them with a new self-signed pair.

Without your own name, each boot checks the instance's names. After a stop and start that changed the public address, the next boot issues a new certificate for the new name. Nothing changes on a boot where the names are the same.

All archive state is on the data volume:

findmnt -no SOURCE,SIZE,TARGET /var/lib/dcm4chee
sudo ls /var/lib/dcm4chee

/dev/nvme1n1 31.2G /var/lib/dcm4chee db ldap lost+found slapd.d storage wildfly

To grow the volume, increase its size in the EC2 console (or aws ec2 modify-volume), then run sudo resize2fs /dev/nvme1n1. Check the device name with findmnt.

The simplest complete backup is an EBS snapshot of both volumes (or AWS Backup on the instance). For a consistent snapshot, stop the stack first with sudo systemctl stop dcm4chee-arc, and start it again afterwards.

Every service is enabled, so the archive returns after a reboot or a stop and start. Unattended security upgrades keep the operating system, nginx and Docker patched:

systemctl is-enabled docker dcm4chee-arc dcm4chee-set-host nginx unattended-upgrades

enabled enabled enabled enabled enabled

The secrets that the containers use are files under /etc/dcm4chee (root only). The compose project is /opt/dcm4chee/compose.yaml. Its images are pinned and are never pulled at boot.