How to use osimis/orthanc Docker images ?

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.

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.

{
  "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).

{
  "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).

{
  "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).

Osimis Orthanc Bundle Setup Procedures

Before starting Orthanc, setup procedures may run to help more easily configure Orthanc and its plugins. Benefits include:

• No need to create an additional image layer in many cases.
• Straightforward configuration via a Docker compose file.
• Easy and consistent use of Docker secrets.
• Easy setup of plugins.

Access Control

Settings:

If you provide the remote-access.json configuration file, it will be used. Otherwise, it will be generated on the fly at startup. You can override its default values using the environment variables described above.

See discussion on bundle defaults below to disable the generation of that file.

Authorization

Settings:

Authorization.WebService

Authorization.TokenGetArguments

Authorization.TokenHttpHeaders

Authorization.UncheckedResources

Authorization.UncheckedFolders

Authorization.UncheckedLevels

If you provide the authorization.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables* and the configuration file will be generated on the fly at startup.

The plugin is enabled as soon as you provide a configuration file or one is generated.

*The AUTHZ_ENABLED setting alone does not automatically trigger the generation of the configuration file. See discussion on bundle defaults below.

Azure Storage

Settings:

Docker secrets:

If you provide the azure-storage.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables* and the configuration file will be generated on the fly at startup.

The plugin is enabled as soon as you provide a configuration file or one is generated.

When the configuration file is generated by the setup procedure, the BlobStorage.Enable Orthanc setting is automatically set to true.

*The AZSTOR_ENABLED setting alone does not automatically trigger the generation of the configuration file. See discussion on bundle defaults below.

DICOM

Settings:

DICOM_UNKNOWN_SOP_CLASS_ACCEPTED

UnknownSopClassAccepted

If you provide the dicom.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables and the configuration file will be generated on the fly at startup.

DICOMweb

Settings:

If you provide the dicomweb.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables* and the configuration file will be generated on the fly at startup.

The plugin is enabled as soon as you provide a configuration file or one is generated.

When the configuration file is generated by the setup procedure, the DicomWeb.Enable Orthanc setting is automatically set to true.

*The DW_ENABLED setting alone does not automatically trigger the generation of the configuration file. See discussion on bundle defaults below.

General

Settings:

If you provide the orthanc.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables and the configuration file will be generated on the fly at startup.

Google Cloud Platform DICOM Store Exchange

Settings:

GoogleCloudPlatform.Accounts

GoogleCloudPlatform.Accounts[0].Project

GoogleCloudPlatform.Accounts[0].Location

GoogleCloudPlatform.Accounts[0].Dataset

GoogleCloudPlatform.Accounts[0].DicomStore

GCP_DICOM_AUTHORIZED_SERVICE_ACCOUNT_FILE

GoogleCloudPlatform.Accounts[0].ServiceAccountFile

GCP_DICOM_AUTHORIZED_USER_FILE

GoogleCloudPlatform.Accounts[0].AuthorizedUserFile

GCP_DICOM_AUTHORIZED_USER_CLIENT_ID

GoogleCloudPlatform.Accounts[0].AuthorizedUserClientId

GCP_DICOM_AUTHORIZED_USER_CLIENT_SECRET

GoogleCloudPlatform.Accounts[0].AuthorizedUserClientSecret

"AUTHORIZED_USER_CLIENT_SECRET"

GCP_DICOM_AUTHORIZED_USER_REFRESH_TOKEN

GoogleCloudPlatform.Accounts[0].RefreshToken

"AUTHORIZED_USER_REFRESH_TOKEN"

GCP_DICOM_BASE_URL

"https://healthcare.googleapis.com/v1beta1/"

GoogleCloudPlatform.BaseUrl

GCP_DICOM_ENABLED*

"false"

If you provide the gcp-dicom.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables* and the configuration file will be generated on the fly at startup.

The plugin is enabled as soon as you provide a configuration file or one is generated.

*The GCP_DICOM_ENABLED setting alone does not automatically trigger the generation of the configuration file. See discussion on bundle defaults below.

GCP_DICOM_ACCOUNTS cannot be used with any other settings with the exception of GCP_DICOM_BASE_URL and GCP_DICOM_ENABLED. Beware that if you need to configure multiple GCP accounts, you need to use GCP_DICOM_ACCOUNTS.

**When GCP_DICOM_ACCOUNT_NAME is set, exactly one of GCP_DICOM_AUTHORIZED_SERVICE_ACCOUNT_FILE, GCP_DICOM_AUTHORIZED_USER_FILE or GCP_DICOM_AUTHORIZED_USER_CLIENT_ID must be set.

The Orthanc DICOMweb plugin must be enabled explicitly.

Notice: This plugin allows queries and transfers to and from GCP DICOM stores, it does not use a GCP DICOM store as a storage backend for Orthanc.

Important: It is recommended to set HTTP_CL_VERIFY_PEERS to true. This is the default bundle configuration value, and the relevant bundle setup procedure (HTTP) generates the relevant configuration file by default as well, meaning that unless you disable the automatic generation with HTTP_BUNDLE_DEFAULTS set to false or if you don't set HTTP_CL_VERIFY_PEERS explicitly, you have nothing to do.

HTTP

Settings:

"true"

KeepAlive

HTTP_TCP_NODELAY

"true"

TcpNoDelay

HTTP_REQUEST_TIMEOUT

"30"

HttpRequestTimeout

If you provide the http.json configuration file, it will be used. Otherwise, it will be generated on the fly at startup. You can override its default values using the environment variables described above.

See discussion on bundle defaults below to disable the generation of that file.

Import

Settings:

Listener

Settings:

If you provide the listener.json configuration file, it will be used. Otherwise, it will be generated on the fly at startup. You can override its default values using the environment variables described above.

See discussion on bundle defaults below to disable the generation of that file.

Incompatible with Access Control. May be made compatible in the future if LISTENER_LISTEN_ALL_ADDR is fixed or removed.

Locale

Settings:

If you provide the locale.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables and the configuration file will be generated on the fly at startup.

Lua

Settings:

FROM osimis/orthanc:20.3.0
ENV LUA_SCRIPTS="[\"/etc/orthanc/send_study.lua\"]"
ENV LUA_OPTIONS="{\"send-study\":{\"connector-service\":\"http:\/\/hub-connector-service\"}}"
COPY send_study.lua /etc/orthanc/send_study.lua

local config = GetOrthancConfiguration()
local connectorService = config["LuaOptions"]["send-study"]["connector-service"]

This variable was introduced in version 18.9.1.

If you provide the lua.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables and the configuration file will be generated on the fly at startup.

Microsoft SQL Server

Settings:

Docker secrets:

If you provide the mssql.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables* and the configuration file will be generated on the fly at startup.

The plugin is enabled as soon as you provide a configuration file or one is generated.

When the configuration file is generated by the setup procedure, the MSSQL.EnableIndex Orthanc setting is automatically set to true, and the MSSQL.EnableStorage Orthanc setting is automatically set to false.

*The MSSQL_ENABLED setting alone does not automatically trigger the generation of the configuration file. See discussion on bundle defaults below.

MySQL

This plugin and settings have been introduced in version 18.7.2

Settings:

Docker secrets:

If you provide the mysql.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables* and the configuration file will be generated on the fly at startup.

The plugin is enabled as soon as you provide a configuration file or one is generated.

*The MYSQL_ENABLED, MYSQL_INDEX_ENABLED and MYSQL_STORAGE_ENABLED settings alone do not automatically trigger the generation of the configuration file. See discussion on bundle defaults below.

Orthanc Web Viewer

Settings:

Osimis Web Viewer

Settings:

WVB_INSTANCE_INFO_CACHE_ENABLED

WebViewer.InstanceInfoCacheEnabled

If you provide the osimis-webviewer.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables* and the configuration file will be generated on the fly at startup.

The plugin is enabled as soon as you provide a configuration file or one is generated.

Incompatible with Osimis Web Viewer Pro.

*The WVB_ENABLED and WVB_ALPHA_ENABLED settings alone do not automatically trigger the generation of the configuration file. See discussion on bundle defaults below.

Osimis Web Viewer Pro

Settings:

WVP_INSTANCE_INFO_CACHE_ENABLED

WebViewer.InstanceInfoCacheEnabled

Docker secrets:

If you provide the osimis-webviewer-pro.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables* and the configuration file will be generated on the fly at startup.

The plugin is enabled as soon as you provide a configuration file or one is generated.

Incompatible with Osimis Web Viewer.

*The WVP_ENABLED and WVP_ALPHA_ENABLED settings alone do not automatically trigger the generation of the configuration file. See discussion on bundle defaults below.

Peering

Settings:

If you provide the peering.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables and the configuration file will be generated on the fly at startup.

PostgreSQL

Settings:

Docker secrets:

If you provide the postgresql.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables* and the configuration file will be generated on the fly at startup.

The plugin is enabled as soon as you provide a configuration file or one is generated.

*The PG_ENABLED, PG_INDEX_ENABLED and PG_STORAGE_ENABLED settings alone do not automatically trigger the generation of the configuration file. See discussion on bundle defaults below.

Plugins

Settings:

If you provide the plugins.json configuration file, it will be used. Otherwise, it will be generated on the fly at startup. You can override its default values using the environment variables described above.

See discussion on bundle defaults below to disable the generation of that file.

Resource Stability

Settings:

If you provide the resource-stability.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables and the configuration file will be generated on the fly at startup.

Scheduler

Settings:

If you provide the scheduler.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables and the configuration file will be generated on the fly at startup.

Serve Folders

Settings:

If you provide the serve-folders.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables* and the configuration file will be generated on the fly at startup.

The plugin is enabled as soon as you provide a configuration file or one is generated.

*The SERVEFOLDERS_ENABLED setting alone does not automatically trigger the generation of the configuration file. See discussion on bundle defaults below.

Storage

Settings:

If you provide the storage.json configuration file, it will be used. Otherwise, it will be generated on the fly at startup. You can override its default values using the environment variables described above.

See discussion on bundle defaults below to disable the generation of that file.

Transfers accelerator

libOrthancTransfers

Settings:

TRANSFERS_RETRIES

Transfers.MaxHttpRetries

TRANSFERS_THREADS

Transfers.Threads

TRANSFERS_ENABLED*

If you provide the transfers.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables* and the configuration file will be generated on the fly at startup.

The plugin is enabled as soon as you provide a configuration file or one is generated.

*The TRANSFERS_ENABLED setting alone does not automatically trigger the generation of the configuration file. See discussion on bundle defaults below.

User metadata

Settings:

USERMETADATA

UserMetadata

If you provide the usermetadata.json configuration file, it will be used. Otherwise, you may specify the USERMETADATA environment variable and the configuration file will be generated on the fly at startup.

Worklists

Settings:

If you provide the worklists.json configuration file, it will be used. Otherwise, you may specify one or multiple environment variables* and the configuration file will be generated on the fly at startup.

The plugin is enabled as soon as you provide a configuration file or one is generated.

When the configuration file is generated by the setup procedure, the Worklists.Enable Orthanc setting is automatically set to true.

*The WL_ENABLED setting alone does not automatically trigger the generation of the configuration file. See discussion on bundle defaults below.

Whole-Slide Imaging

Settings:

Incompatible with Whole-Slide Imaging (experimental).

Whole-Slide Imaging (experimental)

Settings:

Incompatible with Whole-Slide Imaging.

Verbose Mode

To run Orthanc in verbose mode (--verbose command-line switch), set the VERBOSE_ENABLED environment variable to true.

To run Orthanc in trace mode (--trace command-line switch), set the TRACE_ENABLED environment variable to true.

Other command line options

To run Orthanc with the --unlock command-line switch to unlock a locked database, set the UNLOCK environment variable to true.

To run Orthanc with the --no-jobs command-line switch to prevent Orthanc from reloading the saved jobs, set the NO_JOBS environment variable to true.

Bundle Defaults

If you want a setup procedure to generate its configuration file with the bundle defaults without specifying any setting via environment variables, you may set the special {PREFIX}_BUNDLE_DEFAULTS environment variable to true. Otherwise when no configuration file is generated then Orthanc and relevant plugins will use their own default values.

It is important to note that plugins managed by a setup procedure are often automatically enabled (moved to /usr/share/orthanc/plugins) whenever the configuration file for that setup procedure is successfully generated. This means that you usually don't have to set {PREFIX}_ENABLED when you set {PREFIX}_BUNDLE_DEFAULTS.

Conversely, if a setup procedure is set to generate its configuration file by default, you can disable that behavior by setting {PREFIX}_BUNDLE_DEFAULTS to false, thus ensuring the defaults of Orthanc and relevant plugins are used instead. This is not recommended as there is usually a good reason why the bundle forces a specific configuration by default different than that of Orthanc and its plugins, and usually pertains to the environment (i.e. useful or necessary because it is running in a container).

Configuration File Generation

If any part of the generation of a configuration file fails for whatever reason (e.g. a mandatory setting was not provided) then the file will simply not be written out and any corresponding plugins managed by the setup procedure will not be enabled automatically (but will still be loaded if enabled via the {PREFIX}_ENABLED environment variable explicitly and will thus use their own defaults).

Docker Secrets

Every setting containing sensitive information can typically be defined as a Docker secret instead of an environment variable. Internally, the value for that setting will be read from the Docker secret file using the expected file name (always configurable with a corresponding *_SECRET environment variable and which defaults to the same name as the corresponding environment variable itself) and used identically to the corresponding environment variable.

This is always preferred, as environment variables often leak in log outputs, debug environment captures or are inadvertently propagated to child processes or third-party plugins which may leak them in various other ways.

Network connectivity when using Docker for Windows

You may encounter the following error when using Docker for Windows.

C:\Program Files\Docker\Docker\Resources\bin\docker.exe: Error response from daemon: driver failed programming external connectivity on endpoint objective_hermann (...): Error starting userland proxy: mkdir /port/tcp:0.0.0.0:8044:tcp:172.17.0.2:8042: input/output error.

First, try again with an elevated prompt (run cmd.exe or Powershell in administrator mode). If might still happen, though. The cause of this error is unclear, but launching a simple Hello World docker with:

docker run -p 8080:8080 hello-world

triggered a dialog box asking whether to authorize network access for the vpnkit application. After accepting it, it became possible to launch the Orthanc image with standard ports. Weird thing is, you may not choose any available port. Some do work and some do not. Advice or information regarding this error message would be much appreciated.