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.


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.

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

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

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

Adding your own configuration

You'll probably want to fine tune Orthanc to your own needs.  Thanks to setup procedures, you can either tune the configuration by providing your own configuration file or by defining environment variables.

Example: tuning the HTTP settings by providing your own configuration file

You shall add your own http.json file in /etc/orthanc/ folder.  It will simply replace the default file of the osimis/orthanc image.

Example: tuning the HTTP settings by providing environment variable

Consider you want to change the HttpTimeout setting but keep all default HTTP parameters; you might just define an environment variable either:

  • by adding this line in your Dockerfile
  • by defining the environment variable in your docker run command.
  • by defining the environment variable in a docker-compose.yml` file


Example: using the postgresql plugin by providing your own configuration file

If you provide a file named postgresql.json, the plugin will be loaded automatically (it will be moved from the /usr/share/orthanc/plugins-disabled folder to /usr/share/orthanc/plugins folder) and it will use your configuration file.

Example: using the postgresql plugin by providing environment variables

You might also configure the postgresql plugin by defining environment variable in your Dockerfile

Example: using the osimis/orthanc images the old way

Before providing osimis/orthanc images, Osimis has been providing osimis/orthanc-webviewer-plugin images.  People were used to copy a single big orthanc.json file in /etc/orthanc.  We highly recommend using Orthanc default values as much as possible and providing only a few custom configurations in multiple small configuration files.  However, for those who want to get back to the old behaviour, here's a sample Dockerfile:


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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file nameremote-access.json
Configuration file generated by defaultYes
Bundle version18.6.0 and later

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
AC_ALLOW_REMOTEJSON boolean"true"RemoteAccessAllowed
AC_AUTHENTICATION_ENABLEDJSON boolean"true"AuthenticationEnabledIntroduced in 19.9.1, default value is "true" since 19.10.2
AC_REGISTERED_USERSJSON object{}RegisteredUsersIntroduced in 19.10.2.
If you don't define any users, Orthanc will generate a default orthanc:orthanc user and display security warnings in the logs and in the Orthanc Explorer requesting you to configure another more secure user.  This way, you're able to quick-start an orthanc without providing any configuration but you should of course configure this when using Orthanc in production.

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file nameauthorization.json
PluginlibOrthancAuthorization
Related sampleshttps://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/authorization-plugin/

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
AUTHZ_WEBSERVICEStringMandatory
Authorization.WebService
http://book.orthanc-server.com/plugins/authorization.html
AUTHZ_TOKEN_GET_ARGUMENTSJSON Array[]
Authorization.TokenGetArguments
http://book.orthanc-server.com/plugins/authorization.html
AUTHZ_TOKEN_HTTP_HEADERSJSON Array[]
Authorization.TokenHttpHeaders
http://book.orthanc-server.com/plugins/authorization.html
AUTHZ_UNCHECKED_RESOURCESJSON Array[]
Authorization.UncheckedResources
http://book.orthanc-server.com/plugins/authorization.html
AUTHZ_UNCHECKED_FOLDERSJSON Array[]
Authorization.UncheckedFolders
http://book.orthanc-server.com/plugins/authorization.html
AUTHZ_UNCHECKED_LEVELSJSON Array[]
Authorization.UncheckedLevels

http://book.orthanc-server.com/plugins/authorization.html

AUTHZ_ENABLEDBooleanfalse
Force-enable/disable plugin (see below).

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

Imageosimis/orthanc-pro
Configuration file nameazure-storage.json
PluginlibOrthancBlobStorage

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
AZSTOR_ACC_NAMEJSON stringMandatoryBlobStorage.AccountName
AZSTOR_ACC_KEYJSON stringMandatoryBlobStorage.AccountKeyNot recommended, use Docker secret instead.
AZSTOR_ACC_KEY_SECRETString"AZSTOR_ACC_KEY"
File name for the ACC_KEY Docker secret.
AZSTOR_CONTAINERJSON stringMandatoryBlobStorage.ContainerName
AZSTOR_LICENSE_STRINGJSON stringMandatoryBlobStorage.LicenseStringNot recommended, use Docker secret instead.
AZSTOR_LICENSE_STRING_SECRETString"AZSTOR_LICENSE_STRING"
File name for the LICENSE_STRING Docker secret.
AZSTOR_ENABLED*Boolean"false"
Force-enable/disable plugin (see below).

Docker secrets:

SecretDefault expected file nameCorresponding environment variable
ACC_KEYSee AZSTOR_ACC_KEY_SECRETAZSTOR_ACC_KEY
LICENSE_STRINGSee AZSTOR_LICENSE_STRING_SECRETAZSTOR_LICENSE_STRING

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:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
DICOM_AETJSON string"ORTHANC"DicomAethttp://book.orthanc-server.com/dicom-guide.html#configuring-orthanc
DICOM_MODALITIESJSON object{}DicomModalities

http://book.orthanc-server.com/dicom-guide.html#configuring-orthanc

http://book.orthanc-server.com/faq/query-retrieve.html

DICOM_PORTJSON number4242DicomPort
DICOM_SCP_TIMEOUTJSON number30DicomScpTimeout
DICOM_SCU_TIMEOUTJSON number10DicomScuTimeout
DICOM_AET_CHECK_ENABLEDJSON boolean"false"DicomCheckCalledAet
DICOM_CHECK_MODALITY_HOST_ENABLEDJSON boolean"false"DicomCheckModalityHost
DICOM_STRICT_AET_COMPARISON_ENABLEDJSON boolean"false"StrictAetComparison
DICOM_ALWAYS_ALLOW_ECHO_ENABLEDJSON boolean"true"DicomAlwaysAllowEcho
DICOM_ALWAYS_ALLOW_STORE_ENABLEDJSON boolean"true"DicomAlwaysAllowStore
DICOM_UNKNOWN_SOP_CLASS_ACCEPTED
JSON boolean"false"
UnknownSopClassAccepted
Introduced in 18.7.3
DICOM_SYNCHRONOUS_CMOVEJSON boolean"false"SynchronousCMove

Introduced in 18.9.5.

Default was changed from "false" to "true" in 18.11.0.

Actual behavior was equivalent to synchronous C-MOVE set to "true" in Orthanc 1.3.2 and previous versions.

For information: Upon introduction in Orthanc 1.4, synchronous C-MOVE was set to "false" by default but was later changed to "true".

DICOM_QUERY_RETRIEVE_SIZEJSON number"100"QueryRetrieveSizeIntroduced in 20.3.0
DICOM_DICTIONARYJSON object{}DictionaryIntroduced in 20.3.0

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file namedicomweb.json
PluginlibOrthancDicomWeb
Related sampleshttps://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/dicom-web/

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
DW_ROOTJSON string"/dicom-web/"DicomWeb.Roothttp://book.orthanc-server.com/plugins/dicomweb.html
DW_WADO_URI_ENABLEDJSON boolean"true"DicomWeb.EnableWadohttp://book.orthanc-server.com/plugins/dicomweb.html
DW_WADO_URI_ROOTJSON string"/wado"DicomWeb.WadoRoothttp://book.orthanc-server.com/plugins/dicomweb.html
DW_HOSTJSON string"localhost"DicomWeb.Hosthttp://book.orthanc-server.com/plugins/dicomweb.html
DW_TLSJSON boolean"false"DicomWeb.Sslhttp://book.orthanc-server.com/plugins/dicomweb.html
DW_SERVERSJSON object{}DicomWeb.Servers
DW_STOW_MAX_INSTANCESJSON number10DicomWeb.StowMaxInstanceshttp://book.orthanc-server.com/plugins/dicomweb.html, introduced in version 18.1.5
DW_STOW_MAX_SIZEJSON number10DicomWeb.StowMaxSizehttp://book.orthanc-server.com/plugins/dicomweb.html, introduced in version 18.1.5
DW_ENABLED*Boolean"false"
Force-enable/disable plugin (see below).

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file nameorthanc.json
Configuration file generated by defaultYes
Related sampleshttps://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/basic/

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
NAMEJSON string"ORTHANC"Name
EXECUTE_LUA_ENABLEDBoolean"false"ExecuteLuaEnabledIntroduced in 19.10.2
STORAGE_ACCESS_ON_FINDJSON string"Always"StorageAccessOnFindIntroduced in 20.3.0

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

Imagesosimis/orthanc
osimis/orthanc-pro
Version20.1.0
Configuration file namegcp-dicom.json
Plugin

libOrthancGoogleCloudPlatform

DependencieslibOrthancDicomWeb

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
GCP_DICOM_ACCOUNTSJSON objectAbsent
GoogleCloudPlatform.Accounts
https://book.orthanc-server.com/plugins/google-cloud-platform.html
GCP_DICOM_ACCOUNT_NAMEJSON stringAbsent

GoogleCloudPlatform.Accounts[0]

https://book.orthanc-server.com/plugins/google-cloud-platform.html

GCP_DICOM_PROJECTJSON string

Absent
Mandatory if ACCOUNT_NAME is set

GoogleCloudPlatform.Accounts[0].Project
https://book.orthanc-server.com/plugins/google-cloud-platform.html
GCP_DICOM_LOCATIONJSON stringAbsent
Mandatory if ACCOUNT_NAME is set
GoogleCloudPlatform.Accounts[0].Location
https://book.orthanc-server.com/plugins/google-cloud-platform.html
GCP_DICOM_DATASETJSON stringAbsent
Mandatory if ACCOUNT_NAME is set
GoogleCloudPlatform.Accounts[0].Dataset
https://book.orthanc-server.com/plugins/google-cloud-platform.html
GCP_DICOM_DATASTOREJSON stringAbsent
Mandatory if ACCOUNT_NAME is set
GoogleCloudPlatform.Accounts[0].DicomStore
https://book.orthanc-server.com/plugins/google-cloud-platform.html
GCP_DICOM_AUTHORIZED_SERVICE_ACCOUNT_FILE
JSON stringAbsent**
GoogleCloudPlatform.Accounts[0].ServiceAccountFile
https://book.orthanc-server.com/plugins/google-cloud-platform.html
GCP_DICOM_AUTHORIZED_USER_FILE
JSON stringAbsent**
GoogleCloudPlatform.Accounts[0].AuthorizedUserFile
https://book.orthanc-server.com/plugins/google-cloud-platform.html
GCP_DICOM_AUTHORIZED_USER_CLIENT_ID
JSON stringAbsent**
GoogleCloudPlatform.Accounts[0].AuthorizedUserClientId
https://book.orthanc-server.com/plugins/google-cloud-platform.html
GCP_DICOM_AUTHORIZED_USER_CLIENT_SECRET
JSON stringAbsent
Mandatory if AUTHORIZED_USER_CLIENT_ID is set
GoogleCloudPlatform.Accounts[0].AuthorizedUserClientSecret
https://book.orthanc-server.com/plugins/google-cloud-platform.html
GCP_DICOM_AUTHORIZED_USER_CLIENT_SECRET_SECRETString
"AUTHORIZED_USER_CLIENT_SECRET"

File name for the AUTHORIZED_USER_CLIENT Docker secret

GCP_DICOM_AUTHORIZED_USER_REFRESH_TOKEN
JSON stringAbsent
Mandatory if AUTHORIZED_USER_CLIENT_ID is set
GoogleCloudPlatform.Accounts[0].RefreshToken
https://book.orthanc-server.com/plugins/google-cloud-platform.html
GCP_DICOM_AUTHORIZED_USER_REFRESH_TOKEN_SECRETString
"AUTHORIZED_USER_REFRESH_TOKEN"

File name for the AUTHORIZED_USER_REFRESH_TOKEN Docker secret
GCP_DICOM_BASE_URL
JSON string
"https://healthcare.googleapis.com/v1beta1/"
GoogleCloudPlatform.BaseUrl
https://book.orthanc-server.com/plugins/google-cloud-platform.html
GCP_DICOM_ENABLED*
Boolean
"false"

Force-enable/disable plugin (see below).

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file namehttp.json
Configuration file generated by defaultYes
Related sampleshttps://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/full-tls/

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
HTTP_CL_TIMEOUTJSON number"0"HttpTimeout
HTTP_CL_VERIFY_PEERSJSON boolean"true"HttpsVerifyPeers
HTTP_CL_PROXYJSON string""HttpProxy
HTTP_CL_CA_CERTSJSON string"/etc/ssl/certs/ca-certificates.crt"HttpsCACertificates
HTTP_PORTJSON number"8042"HttpPort
HTTP_KEEP_ALIVEJSON boolean
"true"
KeepAlive
Should be set to "false" in Orthanc <= 1.5.1
HTTP_TCP_NODELAY
JSON boolean
"true"
TcpNoDelay
Introduced in Orthanc 1.5.2
HTTP_REQUEST_TIMEOUT
JSON number
"30"
HttpRequestTimeout
Introduced in Orthanc 1.5.8

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

Images

osimis/orthanc
osimis/orthanc-pro

Configuration file nameimport.json
Version18.9.4+

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
IMPORT_OVERWRITE_INSTANCESJSON boolean"false"OverwriteInstanceshttps://bitbucket.org/sjodogne/orthanc/src/Orthanc-1.4.2/NEWS

Listener

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file namelistener.json

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
LISTENER_LISTEN_ALL_ADDRJSON boolean"true"RemoteAccessAllowed

Deprecated (since 18.6.0). This setting never had an impact on which network address interfaces Orthanc would bind to, and as of Orthanc 1.3.2 it is impossible to configure this. This setting might be recommended again if the necessary changes are applied upstream and leveraged in the setup procedure.

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file namelocale.json

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
LOCALEJSON string"en_US.UTF-8"LocaleIf you don't set this explicitly, Orthanc will use the system locale by default.

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file namelua.json
Configuration file generated by defaultNo
Related samples-

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
LUA_SCRIPTSJSON list[]LuaScriptsYou need to escape the quotes. i.e:  LUA_SCRIPTS="[\"/etc/orthanc/sample.lua\"]"
LUA_OPTIONSJSON object{}LuaOptions

Introduced in version 20.3.0.

This is not Orthanc specific but is a workaround to be able to pass variables to Lua scripts.

Example of use:

Dockerfile

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

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

Imageosimis/orthanc-pro
Configuration file namemssql.json
PluginlibOrthancMsSqlIndex

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
MSSQL_CONNECTION_STRINGJSON stringMandatoryMSSQL.ConnectionStringNot recommended, use Docker secret instead.
MSSQL_CONNECTION_STRING_SECRETString"MSSQL_CONNECTION_STRING"
File name for the CONNECTION_STRING Docker secret.
MSSQL_LICENSE_STRINGJSON stringMandatoryMSSQL.LicenseStringNot recommended, use Docker secret instead.
MSSQL_LICENSE_STRING_SECRETString"MSSQL_LICENSE_STRING"
File name for the LICENSE_STRING Docker secret.
MSSQL_LOCKJSON boolean"false"MSSQL.Lock
MSSQL_MAXIMUM_CONNECTION_RETRIESJSON number"10"MSSQL.MaximumConnectionRetriesNumber of retries when connecting to the DB at startup
MSSQL_CONNECTION_RETRY_INTERVALJSON number"5"MSSQL.ConnectionRetryIntervalInterval between retries when connecting to the DB at startup
MSSQL_ENABLED*Boolean"false"
Force-enable/disable plugin (see below).

Docker secrets:

SecretDefault expected file nameCorresponding environment variable
CONNECTION_STRINGSee MSSQL_CONNECTION_STRING_SECRETMSSQL_CONNECTION_STRING
LICENSE_STRINGSee MSSQL_LICENSE_STRING_SECRETMSSQL_LICENSE_STRING

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file namemysql.json
Plugins

libOrthancMySQLIndex
libOrthancMySQLStorage

Related sampleshttps://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/mysql-easy/

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
MYSQL_INDEX_ENABLED*JSON boolean"true"MySQL.EnableIndexhttp://book.orthanc-server.com/plugins/mysql.html
Force-enable/disable index plugin.
Takes precedence over MYSQL_ENABLED.
MYSQL_STORAGE_ENABLED*JSON boolean"false"MySQL.EnableStorage

http://book.orthanc-server.com/plugins/mysql.html
Force-enable/disable storage plugin.
Takes precedence over MYSQL_ENABLED.

MYSQL_HOSTJSON stringMandatoryMySQL.Hosthttp://book.orthanc-server.com/plugins/mysql.html
MYSQL_PORTJSON number"3306"MySQL.Porthttp://book.orthanc-server.com/plugins/mysql.html
MYSQL_DBJSON string"mysql"MySQL.Databasehttp://book.orthanc-server.com/plugins/mysql.html
MYSQL_USERJSON string"root"MySQL.Usernamehttp://book.orthanc-server.com/plugins/mysql.html
MYSQL_PASSWORDJSON stringAbsentMySQL.Password

http://book.orthanc-server.com/plugins/mysql.html

Not recommended, use Docker secret instead.

When left unspecified, the MySQL.Password is not specified in generated configuration files either.

MYSQL_PASSWORD_SECRETString"MYSQL_PASSWORD"
File name for the PASSWORD Docker secret.
MYSQL_LOCKJSON boolean"false"MySQL.Lockhttp://book.orthanc-server.com/plugins/mysql.html
MYSQL_ENABLED*Boolean"false"
Force-enable/disable plugins (see below).

Docker secrets:

SecretDefault expected file nameCorresponding environment variable
PASSWORDSee MYSQL_PASSWORD_SECRETMYSQL_PASSWORD

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_ENABLEDMYSQL_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

Imagesosimis/orthanc
osimis/orthanc-pro
PluginlibOrthancWebViewer

Settings:

Environment variable nameInterpreted asDefault valueComment
OWV_ENABLEDBoolean"false"Enable plugin.

Osimis Web Viewer

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file nameosimis-webviewer.json
Plugin

libOsimisWebViewer
libOsimisWebViewerAlpha (see WVB_ALPHA_ENABLED setting)

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
WVB_ANNOTATIONS_STORAGE_ENABLEDJSON boolean"false"WebViewer.AnnotationStorageEnabledsee WebViewer configuration file documentation
WVB_COMBINED_TOOL_ENABLEDJSON boolean"false"WebViewer.CombinedToolEnabledsee WebViewer configuration file documentation
WVB_CROSS_HAIR_ENABLEDJSON boolean"true"WebViewer.CrossHairEnabledIntroduced in version 19.9.3
WVB_DEFAULT_LANGUAGE JSON string"en"WebViewer.DefaultLanguagesee WebViewer configuration file documentation
WVB_DEFAULT_SELECTED_TOOL JSON string"zoom"WebViewer.DefaultSelectedToolsee WebViewer configuration file documentation
WVB_DOWNLOAD_AS_JPEG_ENABLEDJSON boolean"false"WebViewer.DownloadAsJpegEnabledIntroduced in version 19.6.3.
WVB_INSTANCE_INFO_CACHE_ENABLED
JSON boolean"false"
WebViewer.InstanceInfoCacheEnabled
Introduced in version 19.11.1 see WebViewer configuration file documentation
WVB_KEY_IMAGE_CAPTURE_ENABLEDJSON boolean"false"WebViewer.KeyImageCaptureEnabledsee WebViewer configuration file documentation, introduced in version 18.1.3
WVB_KEYBOARD_SHORTCUTS_ENABLEDJSON boolean"false"WebViewer.KeyboardShortcutsEnabledIntroduced in version 18.3.5.
WVB_OPEN_ALL_PATIENT_STUDIESJSON boolean"true"WebViewer.OpenAllPatientStudiessee WebViewer configuration file documentation
WVB_PRINT_ENABLEDJSON boolean"false"WebViewer.PrintEnabledIntroduced in version 19.6.3
WVB_REFERENCE_LINES_ENABLEDJSON boolean"true"WebViewer.ReferenceLinesEnabledIntroduced in version 19.9.3
WVB_SERIES_TO_IGNOREJSON object{}WebViewer.SeriesToIgnoreIntroduced in version 19.2.0
WVB_STUDY_DOWNLOAD_ENABLEDJSON boolean"true"WebViewer.StudyDownloadEnabledsee WebViewer configuration file documentation
WVB_SYNCHRONIZED_BROWSING_ENABLEDJSON boolean"true"WebViewer.SynchronizedBrowsingEnabledIntroduced in version 19.9.3
WVB_TOGGLE_OVERLAY_TEXT_BUTTON_ENABLEDJSON boolean"false"WebViewer.ToggleOverlayTextButtonEnabledsee WebViewer configuration file documentation
WVB_VIDEO_ENABLEDJSON boolean"true"WebViewer.VideoDisplayEnabledsee WebViewer configuration file documentation
WVB_ALPHA_ENABLED*Boolean"false"
Use libOsimisWebViewerAlpha plugin instead of libOsimisWebViewer plugin. Implies WVB_ENABLED.
WVB_ENABLED*Boolean"false"

Force-enable/disable plugin (see below).

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

Imageosimis/orthanc
Configuration file nameosimis-webviewer-pro.json
PluginslibOsimisWebViewerPro
libOsimisWebViewerProAlpha (see WVP_ALPHA_ENABLED setting)
Related sampleshttps://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/webviewer-pro+liveshare/

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
WVP_ANNOTATIONS_STORAGE_ENABLED JSON boolean"false"WebViewer.AnnotationStorageEnabledsee WebViewer configuration file documentation
WVP_COMBINED_TOOL_ENABLEDJSON boolean"false"WebViewer.CombinedToolEnabledsee WebViewer configuration file documentation
WVP_CROSS_HAIR_ENABLEDJSON boolean"true"WebViewer.CrossHairEnabledIntroduced in version 19.9.3
WVP_DEFAULT_LANGUAGE JSON string"en"WebViewer.DefaultLanguagesee WebViewer configuration file documentation
WVP_DEFAULT_SELECTED_TOOL JSON string"zoom"WebViewer.DefaultSelectedToolsee WebViewer configuration file documentation
WVP_DOWNLOAD_AS_JPEG_ENABLEDJSON boolean"false"WebViewer.DownloadAsJpegEnabledIntroduced in version 19.6.3.
WVP_INSTANCE_INFO_CACHE_ENABLED
JSON boolean"false"
WebViewer.InstanceInfoCacheEnabled
Introduced in version 19.11.1 see WebViewer configuration file documentation
WVP_KEY_IMAGE_CAPTURE_ENABLEDJSON boolean"false"WebViewer.KeyImageCaptureEnabledsee WebViewer configuration file documentation, introduced in version 18.1.3
WVP_KEYBOARD_SHORTCUTS_ENABLEDJSON boolean"false"WebViewer.KeyboardShortcutsEnabledIntroduced in version 18.3.5.
WVP_OPEN_ALL_PATIENT_STUDIESJSON boolean"true"WebViewer.OpenAllPatientStudiessee WebViewer configuration file documentation
WVP_PRINT_ENABLEDJSON boolean"false"WebViewer.PrintEnabledIntroduced in version 19.6.3
WVP_REFERENCE_LINES_ENABLEDJSON boolean"true"WebViewer.ReferenceLinesEnabledIntroduced in version 19.9.3
WVP_SERIES_TO_IGNOREJSON object{}WebViewer.SeriesToIgnoreIntroduced in version 19.2.0
WVP_STUDY_DOWNLOAD_ENABLEDJSON boolean"true"WebViewer.StudyDownloadEnabledsee WebViewer configuration file documentation
WVP_SYNCHRONIZED_BROWSING_ENABLEDJSON boolean"true"WebViewer.SynchronizedBrowsingEnabledIntroduced in version 19.9.3
WVP_TOGGLE_OVERLAY_TEXT_BUTTON_ENABLEDJSON boolean"false"WebViewer.ToggleOverlayTextButtonEnabledsee WebViewer configuration file documentation
WVP_VIDEO_ENABLEDJSON boolean"true"WebViewer.VideoDisplayEnabledsee WebViewer configuration file documentation
WVP_LIVESHARE_ENABLEDJSON boolean"false"WebViewer.LiveshareEnabledsee WebViewer configuration file documentation
WVP_LICENSE_STRINGJSON stringMandatoryWebViewer.LicenseStringNot recommended, use Docker secret instead.
WVP_LICENSE_STRING_SECRETString"WVP_LICENSE_STRING"
File name for the LICENSE_STRING Docker secret.
WVP_ALPHA_ENABLED*Boolean"false"
Use libOsimisWebViewerProAlpha plugin instead of libOsimisWebViewerPro plugin. Implies WVP_ENABLED.
WVP_ENABLED*Boolean"false"
Force-enable/disable plugin (see below).

Docker secrets:

SecretDefault expected file nameCorresponding environment variable
LICENSE_STRINGSee WVP_LICENSE_STRING_SECRETWVP_LICENSE_STRING

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:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
PEERSJSON Object{}OrthancPeershttp://book.orthanc-server.com/faq/features.html#peers

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file namepostgresql.json
Plugins

libOrthancPostgreSQLIndex
libOrthancPostgreSQLStorage

Related sampleshttps://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/postgresql-easy/
https://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/postgresql/

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
PG_INDEX_ENABLED*JSON boolean"true"PostgreSQL.EnableIndexhttp://book.orthanc-server.com/plugins/postgresql.html
Force-enable/disable index plugin.
Takes precedence over PG_ENABLED.
PG_STORAGE_ENABLED*JSON boolean"false"PostgreSQL.EnableStorage

http://book.orthanc-server.com/plugins/postgresql.html
Force-enable/disable storage plugin.
Takes precedence over PG_ENABLED.

PG_HOSTJSON stringMandatoryPostgreSQL.Hosthttp://book.orthanc-server.com/plugins/postgresql.html
PG_PORTJSON number"5432"PostgreSQL.Porthttp://book.orthanc-server.com/plugins/postgresql.html
PG_DBJSON string"postgres"PostgreSQL.Databasehttp://book.orthanc-server.com/plugins/postgresql.html
PG_USERJSON string"postgres"PostgreSQL.Usernamehttp://book.orthanc-server.com/plugins/postgresql.html
PG_PASSWORDJSON stringAbsentPostgreSQL.Password

http://book.orthanc-server.com/plugins/postgresql.html

Not recommended, use Docker secret instead.

When left unspecified, the PostgreSQL.Password is not specified in generated configuration files either.

PG_PASSWORD_SECRETString"PG_PASSWORD"
File name for the PASSWORD Docker secret.
PG_SSLJSON boolean"false"PostgreSQL.EnableSslhttp://book.orthanc-server.com/plugins/postgresql.html
PG_LOCKJSON boolean"false"PostgreSQL.Lockhttp://book.orthanc-server.com/plugins/postgresql.html
PG_ENABLED*Boolean"false"
Force-enable/disable plugins (see below).

Docker secrets:

SecretDefault expected file nameCorresponding environment variable
PASSWORDSee PG_PASSWORD_SECRETPG_PASSWORD

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file nameplugins.json
Configuration file generated by defaultYes

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
PLUGINS_DIRJSON string"/usr/share/orthanc/plugins"Plugins

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file nameresource-stability.json

Settings:

Environment variable nameInterpreted asDefault valueOrthanc setting
STABLE_AGEJSON number"60"StableAge

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file namescheduler.json

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
SCHED_MAX_JOBSJSON number"10"LimitJobsDeprecated alias for SCHED_MAX_QUEUED_JOBS.
SCHED_MAX_QUEUED_JOBSJSON number"10"LimitJobsIntroduced in version 20.3.0
SCHED_MAX_CONCURRENT_JOBSJSON number"2"ConcurrentJobsIntroduced in version 20.3.0
SCHED_SAVE_JOBSJSON Boolean"true"SaveJobs
SCHED_JOBS_HISTORY_SIZEJSON number"10"JobsHistorySizeIntroduced in version 20.3.0

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file nameserve-folders.json
PluginlibServeFolders
Related sampleshttps://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/serve-folders/

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
SERVEFOLDERS_ALLOW_CACHEJSON boolean"false"ServeFolders.AllowCachehttp://book.orthanc-server.com/plugins/serve-folders.html
SERVEFOLDERS_GENERATE_ETAGSJSON boolean"true"ServeFolders.GenerateETaghttp://book.orthanc-server.com/plugins/serve-folders.html
SERVEFOLDERS_EXTENSIONSJSON object{}ServeFolders.Extensionshttp://book.orthanc-server.com/plugins/serve-folders.html
SERVEFOLDERS_FOLDERSJSON object{}ServeFolders.Foldershttp://book.orthanc-server.com/plugins/serve-folders.html
SERVEFOLDERS_ENABLEDBoolean"false"
Force-enable/disable plugin (see below).

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file namestorage.json
Configuration file generated by defaultYes
Related sampleshttps://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/alt-storage-dir/

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
STORAGE_DIRJSON string"/var/lib/orthanc/db"StorageDirectoryOrthanc sets IndexDirectory to the value of StorageDirectory if the former is not set.
STORAGE_MAX_SIZEJSON number"0"MaximumStorageSize
STORAGE_MAX_PATIENTSJSON number"0"MaximumPatientCount
STORE_DICOMJSON boolean"true"StoreDicom

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file nametransfers.json
Plugin
libOrthancTransfers
Related sampleshttps://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/transfers-accelerator/

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
TRANSFERS_RETRIES
JSON number0
Transfers.MaxHttpRetries
http://book.orthanc-server.com/plugins/transfers.html
TRANSFERS_THREADS
JSON number6
Transfers.Threads
http://book.orthanc-server.com/plugins/transfers.html
TRANSFERS_BUCKET_SIZEJSON number4096Transfers.BucketSizeIntroduced in 20.3.0
TRANSFERS_CACHE_SIZEJSON number128Transfers.CacheSizeIntroduced in 20.3.0
TRANSFERS_MAX_PUSH_TRANSACTIONSJSON number4Transfers.MaxPushTransactionsIntroduced in 20.3.0
TRANSFERS_ENABLED*
Boolean"false"
Force-enable/disable plugin (see below).

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file nameusermetadata.json

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
USERMETADATA
JSON object{}
UserMetadata
http://book.orthanc-server.com/faq/features.html#user-defined-metadata

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

Imagesosimis/orthanc
osimis/orthanc-pro
Configuration file nameworklists.json
PluginlibModalityWorklists

Settings:

Environment variable nameInterpreted asDefault valueOrthanc settingComment
WL_STORAGE_DIRJSON string"/var/lib/orthanc/worklists"Worklists.Databasehttp://book.orthanc-server.com/plugins/worklists-plugin.html
WL_ENABLED*Boolean"false"
Force-enable/disable plugin (see below).

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

Imagesosimis/orthanc
osimis/orthanc-pro
PluginlibOrthancWSI

Settings:

Environment variablesInterpreted asDefault valueOrthanc settingComment
WSI_ENABLEDBoolean"false"
Enable plugin.

Incompatible with Whole-Slide Imaging (experimental).

Whole-Slide Imaging (experimental)

Imagesosimis/orthanc
osimis/orthanc-pro
PluginlibOrthancWSIx

Settings:

Environment variablesInterpreted asDefault valueOrthanc settingComment
WSIX_ENABLEDBoolean"false"
Enable plugin.

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.