Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Warning

This documentation is valid for osimis/orthanc images up to version 20.4.1.  

The documentation for versions from 20.4.2 is available here.

Note that the new images will maintain the backward compatibility with previous images till June 2021.


Table of Contents

Quickstart

To launch a bare Orthanc server that you can access from any host which can reach the Docker host over the network (on port 80 for HTTP and port 104 for DICOM).

docker run --publish=80:8042 --publish=104:4242 osimis/orthanc

Remarks:

  • You might need to type sudo in front of every docker command if you are targeting a local Docker engine via a UDS (Unix Domain Socket) and don't have the appropriate permissions to the socket file.
  • If you are running Docker for Windows or Mac and encounter Error starting userland proxy error, please see this.


To enable data persistence for the default SQLite-based Index and filesystem-based Storage backends, bind a Docker volume to /var/lib/orthanc/db.

docker run --publish=80:8042 --publish=104:4242 --volume=/home/johndoe/orthanc-storage:/var/lib/orthanc/db osimis/orthanc 


To use a plugin, simply define an environment variable to enable it.  For example, to enable the Osimis WebViewer Basic plugin, define WVB_ENABLED=true.

docker run --publish=80:8042 --publish=104:4242 --environment=WVB_ENABLED=true --volume=/home/johndoe/orthanc-storage:/var/lib/orthanc/db osimis/orthanc 


For more complex configurations with many environment variables, we recommend using a docker-compose file.

Code Block
version: "2"
services:
        orthanc:
                image: osimis/orthanc
                restart: unless-stopped
                ports: ["104:4242", "80:8042"]
                volumes: ["orthanc-storage:/var/lib/orthanc/db:Z"]
                environment:
                        - NAME=My Orthanc
                        - WVB_ENABLED=true
                        - DICOM_AET=MY_ORTHANC
volumes:
        orthanc-storage:


The osimis/orthanc images come in two flavors:

  • The osimis/orthanc image contains Orthanc and all its open-source plugins.
  • The osimis/orthanc-pro image contains Orthanc, all its open-source plugins and additional commercial plugins (MSSQL, WebViewer Pro and Azure Storage) that require a license string to enable.

Orthanc setup samples

You'll find many samples using the osimis/orthanc images in this repository.  Feel free to clone the repository and adapt the samples to your need.

  1. You can clone work on orthanc setup samples by following priority order:
    1. Basic Orthanc to demonstrate a very basic Orthanc setup.
    2. Orthanc peering (easy variant) to demonstrate Orthanc peering.
    3. Orthanc dicom-web to demonstrate Orthanc dicom-web connectivity.
    4. Orthanc basic DICOM association to demonstrate a simple DICOM association between Orthanc servers (and perform operations such as C-FIND, C-MOVE, C-STORE, C-ECHO).
    5. Orthanc + PostgreSQL to demonstrate how to use the Orthanc PostgreSQL plugin
    6. Orthanc + MySQL to demonstrate how to use the Orthanc MySQL plugin
    7. Orthanc + Transfers accelerator to demonstrate Transfers accelerator plugin.
    8. Orthanc basic HTTP authentication to demonstrate static, basic HTTP authentication.
    9. Sharing Orthanc configurations to demonstrate how to share configuration settings between multiple instance of Orthanc in the same Docker network.
  2. Some usefull docker command lines to explore orthanc setup samples:
    1. docker-compose ps -a
    2. docker ps -a
    3. docker network ls
    4. docker-compose down
    5. docker container ps -a
    6. docker network prune
    7. For the dicom-web sample:

      1. curl http://localhost/studies
      2. curl http://localhost:81/studies
      3. curl http://localhost:80/studies
      4. curl http://localhost:80/dicom-web/servers/bar/stow -X POST -d @- << EOF
        {
        "Resources" : ["1b1cc0c9-c0377071-78e8cd3a-2e382948-a243db42"
        ]
        }
        EOF
    8. For the PostgreSQL (easy) sample:
      1. psql \dt
      2. psql -h localhost -p 5432 postgres
      3. docker container run --rm postgres pg_isready --host=5432
      4. psql -h localhost -p 5432 postgres
      5. psql -h localhost -p 5432 -U postgres

Configuration and Plugins

Typically, you want to tweak Orthanc using one or more configuration files and add plugins for Orthanc to load (and in turn configure the plugins). For this, create a new Docker image layer on top of osimis/orthanc that adds your JSON configuration files in /etc/orthanc and the desired plugins in /usr/share/orthanc/plugins.

Many plugins are already available in the image in /usr/share/orthanc/plugins-disabled; simply move them into /usr/share/orthanc/plugins for Orthanc to load them or, better, define an environment variable to enable the plugin (i.e. PG_ENABLED=true) and the plugin will be copied automatically into /usr/share/orthanc/plugins.

The Osimis Orthanc Bundle runs "Setup Procedures" before starting Orthanc in order to simplify this process. If you use a conventional filename for the configuration file of a supported plugin, the plugin will automatically be moved to the plugins directory and loaded by Orthanc. See below for the filenames to use. Setup procedures also accept settings via environment variables to automatically create configuration files. If a supported plugin doesn't require a configuration file, you can still enable it automatically by using the corresponding *_ENABLED environment variable. See below for the environment variable prefixes to use.

Example: Using the Postgres plugin for the Orthanc Index.

Default content of the image

If you launch the osimis/orthanc image directly without adding your own configuration file and without defining any environment variable, Orthanc will start with these configuration files which slightly differs from Orthanc default configuration:

storage.json

Storage is configured to store files in /var/lib/orthanc/db without any limitations. Very often you'll want to map that directory to a Docker volume.

Code Block
{
  "StorageDirectory": "/var/lib/orthanc/db",
  "MaximumStorageSize": 0,
  "MaximumPatientCount": 0,
  "StoreDicom": true
}

http.json

The HTTP settings are configured to enable Orthanc to validate remote HTTPS certificates (to connect to remote Orthanc peers or DICOMweb servers over HTTPS).

Code Block
{
  "HttpTimeout": 0,
  "HttpsVerifyPeers": true,
  "HttpsCACertificates" : "/etc/ssl/certs/ca-certificates.crt",
  "HttpProxy": "",
  "HttpPort": 8042
}

remote-access.json

If Orthanc is running inside a container, it must be accessible from outside the container (as long as the HTTP port is published on the Docker host via the --publish Docker command line argument).

Code Block
{
  "RemoteAccessAllowed": true
}

plugins.json

Make sure to load plugins from the /usr/share/orthanc/plugins directory.  By default, this folder is empty (all plugins are in /usr/share/orthanc/plugins-disabled directory).

...