Orthanc 1.13.0 on AWS User Guide

Overview

This guide covers launching and using the Orthanc 1.13.0 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg GIS, health and research applications listing on AWS Marketplace; you choose it as the software version when you launch.

Orthanc is a lightweight, open source DICOM server from UCLouvain and the Orthanc Team. It receives medical images from modalities and other PACS over DICOM (C-STORE), stores and indexes them, answers queries and retrievals (C-FIND, C-MOVE), sends images on to other DICOM nodes, and exposes everything through a REST API and the Orthanc Explorer web interface.

The cloudimg image is a hardened, ready-to-use Orthanc server:

• HTTPS from the first boot, with a certificate generated on your instance (an end-entity certificate, not a certificate authority), TLS 1.2 and 1.3 only. Port 80 only redirects to HTTPS, so a password never crosses the network in clear text. Requests for an unknown host name are dropped.
• nginx in front, Orthanc behind it. nginx is the only public web listener. Orthanc's own web server listens on 127.0.0.1:8042 and is also refused from other hosts by the instance's firewall. nginx sets the client address from the real connection (a forged X-Forwarded-For or X-Real-IP is overwritten), limits the API per IPv4 address or IPv6 /64, refuses a password in a query string, refuses a write sent from another site's page, does not serve /tools/shutdown or /tools/reset, and adds HSTS, a Content Security Policy, Referrer-Policy: same-origin and X-Frame-Options: DENY.
• A per-instance administrator. First boot generates the password of the admin account and writes it to a root-only file before Orthanc ever starts. Orthanc's well-known orthanc/orthanc account does not exist: Orthanc refuses to start with no account, with more than one, with a short password or with orthanc/orthanc. Every REST call and every page of Orthanc Explorer needs HTTP Basic authentication.
• DICOM closed until you open it. Orthanc's DICOM port (4242) is not in the security group and is refused by the instance's DICOM peer allow-list, which ships empty. Orthanc checks the called AE title (ORTHANC) and accepts associations only from a modality it knows, by AE title and address. You admit a modality with one command (Step 6).
• An outbound block. C-STORE, C-MOVE and Orthanc peers make Orthanc open connections to addresses an administrator configures, so the orthanc account (and nginx) are refused, by iptables and by systemd, every connection to the EC2 metadata service, to private and reserved ranges and to this instance's own VPC ranges. A fresh instance cannot be turned into a scanner of your network. A modality you admit is let through (Step 6).
• An empty archive. The image ships with an empty database and storage directory: no study, no patient data and no test image. The build stored and deleted synthetic objects only, and checked that none remained.
• An unprivileged service. Orthanc runs as the orthanc account, which has no shell, no password and no sudo rights, under systemd with NoNewPrivileges, a read-only operating system, no capabilities and core dumps off. No plugin and no Lua script are loaded, Lua execution over the API is off, and the API cannot write to the file system.
• Built from pinned source. Orthanc 1.13.0 is compiled from its SHA-256-pinned upstream source with its own DCMTK 3.7.0 (including the upstream patch that limits nested sequences, CVE-2026-44031), pugixml 1.14 and CivetWeb 1.16. Every other library, and nginx, comes from the Ubuntu 24.04 main archive and is patched by Ubuntu's security updates.

What is on the image: Orthanc 1.13.0 with Orthanc Explorer, nginx and iptables from Ubuntu 24.04, cloud-init and the AWS Systems Manager agent.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

Prerequisites

• An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet.
• A security group that allows TCP 22 (SSH), TCP 443 (Orthanc Explorer and the REST API) and TCP 80 (redirects to HTTPS) from the networks your users are on. Do not open 8042: Orthanc's web server listens on the loopback address only. Open TCP 4242 only to the exact addresses of your modalities and PACS (a /32 each), when you admit them (Step 6).
• IMDSv2 enabled (the default for this AMI). The instance reads its own VPC ranges from the metadata service at every boot; with the metadata service switched off, Orthanc does not start (see Step 10).
• For production, a DNS name you control (for example pacs.example.com) and, ideally, a certificate from a certificate authority. Until then the instance uses its public IP address with its own self-signed certificate.
• Medical images are sensitive data. Run the instance in a private subnet or behind a VPN where you can, keep 443 open only to your clinical networks, and follow your organisation's rules for patient data.

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick Orthanc 1.13.0 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large (or larger for big archives or many concurrent users), your key pair, and a security group as above. The archive lives on the root volume under /var/lib/orthanc/db; choose a root volume large enough for your images, or add a data volume (Step 11).

With the AWS CLI (replace the values in angle brackets):

aws ec2 run-instances --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=orthanc}]'

First boot takes about a minute after the instance is running: it generates the administrator password and the certificate, then Orthanc and nginx start. First boot uses the instance's public IP address as its name (or its private address if it has no public one), and also serves its EC2 public DNS name and its private address.

Step 2: Connect to your instance

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

The login message shows the web address and where the password is.

Step 3: Check the services

systemctl is-active cloudimg-orthanc-vpc-cidrs cloudimg-orthanc-egress orthanc nginx

active
active
active
active

(orthanc-firstboot runs once, on the first boot, and shows inactive on every later boot.)

The listeners: SSH, HTTP and HTTPS for everyone, Orthanc's web server on the loopback address, and the DICOM port, which the firewall refuses to every address that is not an admitted modality:

sudo ss -Htln | awk '{print $4}' | sort -u

0.0.0.0:22
0.0.0.0:4242
0.0.0.0:443
0.0.0.0:80
127.0.0.1:8042
127.0.0.53%lo:53
127.0.0.54:53
[::]:22
[::]:443
[::]:80

(127.0.0.53 and 127.0.0.54 are Ubuntu's local DNS resolver.)

Step 4: Read the address, the password and the certificate fingerprint

Everything first boot generated is in /root/orthanc-credentials.txt (root only). The web address, the host name and the certificate's SHA-256 fingerprint:

sudo grep -E '^ORTHANC_(URL|HOST|TLS_SHA256)=' /root/orthanc-credentials.txt

ORTHANC_URL=https://203.0.113.10/
ORTHANC_HOST=203.0.113.10
ORTHANC_TLS_SHA256=D5:FE:02:F5:F5:D4:55:3E:A3:12:DA:0B:C2:9F:FF:89:02:23:59:BA:2E:68:9E:A6:A1:5E:C0:57:6C:2C:18:66

The same file holds ORTHANC_ADMIN_PASSWORD (the account is ORTHANC_ADMIN_USER, admin) and the DICOM settings of Step 6. Read it with sudo cat /root/orthanc-credentials.txt when you need it, and keep the password out of tickets and chat. The certificate is self-signed for this instance: when a browser asks you to trust it, compare its SHA-256 fingerprint with ORTHANC_TLS_SHA256.

A quick check from the instance itself (/healthz is the only path that answers without a password):

curl -sk https://127.0.0.1/healthz -H 'Host: <ORTHANC_HOST>'

ok

Step 5: Sign in to Orthanc Explorer

Open ORTHANC_URL (for example https://203.0.113.10/) in a browser, accept this instance's certificate after comparing its fingerprint, and sign in as admin with ORTHANC_ADMIN_PASSWORD when the browser asks. Orthanc then opens Orthanc Explorer at /app/explorer.html.

Lookup searches studies by patient ID, name, accession number, study date or description; All patients lists every patient; Upload sends DICOM files from your computer; Query/Retrieve queries a modality you admitted; Jobs shows transfers in progress.

A wrong password, no password, or the old default orthanc/orthanc gets 401. The API is limited per IPv4 address or IPv6 /64 (20 requests a second, bursts of 100); beyond that nginx answers 429.

Step 6: Admit a modality (DICOM)

The DICOM settings of this instance:

sudo grep -E '^ORTHANC_DICOM_(AET|PORT)=' /root/orthanc-credentials.txt

ORTHANC_DICOM_AET=ORTHANC
ORTHANC_DICOM_PORT=4242

No modality is admitted on a new instance, so every DICOM association is refused. To let a modality, a PACS or a DICOM viewer talk to Orthanc:

1. Open the security group for that host only: TCP 4242 from <modality-ip>/32.

2. Admit it on the instance by a name, its AE title, its address and its own DICOM port (default 104). This adds it to Orthanc's modality list and to the host allow-list, and restarts Orthanc:

   text sudo orthanc-dicom add CT01 CT01_AET <modality-ip> 104 sudo orthanc-dicom list

On the modality, set the destination to the instance's address, port 4242 and the called AE title ORTHANC. An association from an AE title or an address that is not on the list, or to another called AE title, is refused. sudo orthanc-dicom remove CT01 undoes it (close the security group rule too). Modality addresses are single IPv4 addresses; metadata, link-local, loopback, multicast and documentation ranges are always refused.

To test the connection from Orthanc's side, in Orthanc Explorer open Query/Retrieve, or send a C-ECHO through the API (Step 8): curl ... -X POST https://<ORTHANC_HOST>/modalities/CT01/echo -d '{}'.

Step 7: Send studies to another PACS

A modality you admitted is also a destination: from a study's page in Orthanc Explorer choose Send to DICOM modality, or POST /modalities/CT01/store with the study's ID. A destination on a private address, or anywhere in this VPC, works only once it is admitted with orthanc-dicom add; anything else on those ranges is refused by the outbound block. The metadata service, link-local and loopback addresses can never be admitted.

No Orthanc peer (an HTTP connection to another Orthanc server) is configured on this image. You can add one with the API (PUT /peers/<name>); a peer on a public address works, while a peer on a private address or in this VPC is refused by the outbound block, like the metadata service.

Step 8: The REST API

Every route needs HTTP Basic authentication as admin. A small example from the instance, passing the password to curl in a file only root can read, so it never appears on a command line:

sudo sh -c 'umask 077; printf "user = \"admin:%s\"\n" "$(sed -n "s/^ORTHANC_ADMIN_PASSWORD=//p" /root/orthanc-credentials.txt)" > /root/.orthanc-curl'
sudo curl -s -K /root/.orthanc-curl --cacert /etc/ssl/orthanc/orthanc.crt --resolve <ORTHANC_HOST>:443:127.0.0.1 https://<ORTHANC_HOST>/statistics

{
   "CountInstances" : 0,
   "CountPatients" : 0,
   "CountSeries" : 0,
   "CountStudies" : 0,
   "TotalDiskSize" : "0",
   "TotalDiskSizeMB" : 0,
   "TotalUncompressedSize" : "0",
   "TotalUncompressedSizeMB" : 0
}

Upload a DICOM file with curl -K /root/.orthanc-curl ... -H 'Content-Type: application/dicom' --data-binary @image.dcm https://<ORTHANC_HOST>/instances. Without a password every route answers 401. Uploads are limited to 512 MiB a request. The full API is described in the Orthanc Book. Remove the file when you are done:

sudo shred -u /root/.orthanc-curl

Step 9: Check the whole instance

The self-test proves Orthanc Explorer and its headers over HTTPS, that no password, a wrong password and orthanc/orthanc are refused and this instance's password works, that the API refuses a password in a query string, and that a synthetic study (no patient data) made on the instance is stored, found and then deleted again:

sudo orthanc-selftest

orthanc-selftest: headers: HSTS, CSP frame-ancestors 'none', nosniff, no server version
orthanc-selftest: authentication: anonymous, wrong-password and orthanc:orthanc calls refused (401) on 13 routes; query-string password refused (400)
orthanc-selftest: /system: Orthanc 1.13.0, dcmtk 3.7.0, pugixml 1.14.0, patches civetweb-1.16.patch, dcmtk-3.7.0-max-nested-sequence.patch
orthanc-selftest: synthetic instance created, tags and DICOM file read back (392 bytes)
orthanc-selftest: C-ECHO and C-STORE accepted through the loopback self-modality (AE ORTHANC at 127.0.0.1:4242)
orthanc-selftest: C-STORE refused from an unregistered calling AE; C-ECHO and C-STORE refused to a wrong called AE
orthanc-selftest: synthetic patient deleted; the database is back to 0 patient(s), 0 instance(s)
ORTHANC_SELFTEST_OK

Step 10: The VPC ranges and a fail-closed start

The outbound block refuses Orthanc every private address and this instance's own VPC ranges. The ranges it read at boot:

sudo orthanc-vpc-cidrs --print

source imds
4 172.31.0.0/16

If Orthanc does not start after a reboot. The block is fail closed: the instance reads its VPC ranges from EC2 metadata at every boot (with retries), then from cloud-init's copy, then, on later boots only, from the last list this instance recorded. If none of them gives the ranges (for example after the metadata service was switched off on the instance), Orthanc refuses to start and journalctl -u orthanc -u cloudimg-orthanc-vpc-cidrs says so. Turn IMDSv2 back on (aws ec2 modify-instance-metadata-options --instance-id <id> --http-endpoint enabled --http-tokens required), then:

sudo systemctl restart cloudimg-orthanc-vpc-cidrs cloudimg-orthanc-egress orthanc nginx

Step 11: Storage for your archive

Received images and Orthanc's index (SQLite) are stored under /var/lib/orthanc/db, on the root volume. To make room, either grow the root volume (modify the EBS volume, then sudo growpart /dev/nvme0n1 1 && sudo resize2fs /dev/nvme0n1p1), or attach a dedicated EBS volume and mount it on /var/lib/orthanc/db before you receive images: stop Orthanc (sudo systemctl stop nginx orthanc), format and mount the volume with an /etc/fstab entry by UUID, then sudo chown orthanc:orthanc /var/lib/orthanc/db && sudo chmod 0750 /var/lib/orthanc/db and sudo systemctl start orthanc nginx. Back up the directory (EBS snapshots or AWS Backup) and treat the snapshots as patient data.

Step 12: Change the administrator password

sudo orthanc-set-password            # generates a new random password into /root/orthanc-credentials.txt
sudo orthanc-set-password --stdin    # or reads your own (16 to 128 letters and digits) from standard input

Each restarts Orthanc. After --stdin, the credentials file says the password was set by hand, and the self-test takes it on standard input: sudo orthanc-selftest --password-stdin.

Step 13: Use your own domain and certificate

Point a DNS name at the instance, then make it the instance's name. The command writes the nginx host names (requests for any other name are dropped), generates a new self-signed certificate for the names and restarts nginx:

sudo orthanc-set-domain pacs.example.com

To use a certificate from a certificate authority instead, put the full chain and key in /etc/ssl/orthanc/orthanc.crt and /etc/ssl/orthanc/orthanc.key (root only, mode 0600 for the key), then sudo nginx -t && sudo systemctl reload nginx. If the instance's public address changes after a stop and start, run orthanc-set-domain again with the new address.

Step 14: Versions, licences and source

cat /usr/share/doc/orthanc/README.cloudimg

Orthanc 1.13.0 (GPL-3.0-or-later; see COPYING, NOTICE, BUILD-INFO and WRITTEN-OFFER), built by cloudimg.
Upstream: https://www.orthanc-server.com/  https://orthanc.uclouvain.be/
Corresponding source: /usr/src/orthanc/Orthanc-1.13.0.tar.gz (sha256 90e15e709ba1e472457a35784f6ab66ea87d9ff0b16f12f3fd3cc19e82a6123a)
cloudimg's own files (systemd units, nginx configuration, helper scripts) are under /usr/local/sbin,
/usr/local/lib/cloudimg/orthanc, /etc/nginx/cloudimg and /etc/systemd/system. Configuration: /etc/orthanc.
Guide: https://www.cloudimg.co.uk/guides/orthanc-1-13-0-on-ubuntu-24-04-aws/

Orthanc is free software under the GNU General Public License version 3 or later; its framework is under the GNU Lesser General Public License version 3. The licence texts and the notices of DCMTK, pugixml and CivetWeb are in /usr/share/doc/orthanc. The image was built from the upstream source tarball, which is on the instance with its SHA-256 sums in /usr/src/orthanc; /usr/share/doc/orthanc/BUILD-INFO names every input and patch, and WRITTEN-OFFER explains how to get the corresponding source.

Ubuntu's unattended upgrades keep the operating system, its libraries and nginx patched. Orthanc and its built-in DCMTK do not update automatically: the cloudimg listing adds a new version when the project releases one. DCMTK 3.7.0 has published advisories in tools and parsers Orthanc either does not ship (the DCMTK command-line tools are not on this image) or that are fixed by the patches Orthanc applies; the nested-sequence limit (CVE-2026-44031) is built in, so a deeply nested dataset is refused while Orthanc keeps running. Every DICOM and HTTP path into Orthanc needs an admitted modality or this instance's password. To keep your work across a move to a new instance, copy /var/lib/orthanc/db with Orthanc stopped.

Orthanc is developed by UCLouvain and the Orthanc Team. cloudimg packages and configures it and is not affiliated with or endorsed by the Orthanc project. Orthanc on this image is not a certified medical device; check your own regulatory requirements before clinical use.

Support

cloudimg provides support for this image by email at support@cloudimg.co.uk, 24 hours a day, 7 days a week. Tell us the AMI ID and Region, and include the output of sudo orthanc-selftest and systemctl status orthanc nginx cloudimg-orthanc-vpc-cidrs. For questions about Orthanc itself, see the Orthanc Book and the Orthanc forum.