Contents
Warning
This documentation applies to osimis/orthanc
images from the 20.4.2
version.
Note that these images have been re-written in April 2020. The documentation for older images is still available here
The new images are backward compatible with the previous images except for the Google Cloud Platform configuration.
However, if you’re still using legacy environment variables, you’ll get some warning encouraging you to update to the new namings since the backward compatibility might be removed one day (currently planed in June 2021).
Our commercial partner Osimis publishes separated Docker images that are used by their technical team in order to provide professional support to their customers.
These images have been designed to be used with docker-compose
and
provide a configuration system through:
This repository contains lots of examples on how to use these images. In particular, this example shows all the way that can be used to generate the same configuration in Orthanc.
Any part of the Orthanc configuration file can be configured through an environment variable. Now that Orthanc and its plugins have hundreds of configuration parameter, listing all these environment variable would be too long. That’s why we have defined a standard way of naming the variable:
Orthanc configuration | Environment variable | Sample value |
---|---|---|
StableAge | ORTHANC__STABLE_AGE | 30 |
DicomWeb.Root | ORTHANC__DICOM_WEB__ROOT | /dicom-web/ |
DicomWeb.Servers | ORTHANC__DICOM_WEB__SERVERS | {"sample": [ "http://127.0.0.1/dicom-web/"]} |
To find out an environment variable name from an Orthanc setting
(i.e. DicomWeb.StudiesMetadata
is the path
to a setting):
_
in front.
DicomWeb.StudiesMetadata
now becomes Dicom_Web.Studies_Metadata
__
. Dicom_Web.Studies_Metadata
now becomes
Dicom_Web__Studies_Metadata
Dicom_Web__Studies_Metadata
now becomes
DICOM_WEB__STUDIES_METADATA
ORTHANC__
in front. DICOM_WEB__STUDIES_METADATA
now becomes
ORTHANC__DICOM_WEB__STUDIES_METADATA
Note that, this automatic rule might fail because of 2 capital letters one after each other in some Orthanc settings. Therefore, there are some exceptions to this rule that are however quite intuitive.
Other environment variables are not related to the Orthanc configuration file but can be specified to control the way Orthanc is run.
VERBOSE_STARTUP=true
will allow you to debug the startup process and see
the configuration that has been provided to Orthanc. This setup should be
disabled in production since it might display secret information like passwords
in your logsVERBOSE_ENABLED=true
will start Orthanc with the --verbose
optionTRACE_ENABLED=true
will start Orthanc with the --trace
optionNO_JOBS=true
will start Orthanc with the --no-jobs
optionUNLOCK=true
will start Orthanc with the --unlock
optionMALLOC_ARENA_MAX=10
will control memory usageORTHANC_JSON
can be used to pass a JSON “root” configuration (see below).Configuration files should be stored in the /etc/orthanc/
folder inside the Docker image.
This is done by building an image thanks to a Dockerfile
:
FROM osimis/orthanc
COPY orthanc.json /etc/orthanc/
Configuration files can also be passed as secrets as shown in this docker-compose.yml
:
version: "3.3"
services:
orthanc-file-in-secrets:
image: osimis/orthanc
depends_on: [index-db]
ports: ["8201:8042"]
environment:
VERBOSE_STARTUP: "true"
secrets:
- orthanc.secret.json
secrets:
orthanc.secret.json:
file: orthanc.secret.json
Finally, a whole configuration file can be passed as a JSON through the ORTHANC_JSON
environment variable:
version: "3.3"
services:
orthanc-file-in-env-var:
image: osimis/orthanc
depends_on: [index-db]
ports: ["8200:8042"]
environment:
VERBOSE_ENABLED: "true"
OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED: "true"
ORTHANC_JSON: |
{
"Name": "orthanc-file-in-env-var",
"PostgreSQL" : {
"Host": "index-db",
"Password": "pg-password"
},
"RegisteredUsers": {
"demo": "demo"
}
}
When using your container in a Docker Swarm
or Kubernetes
environment,
it is usually advised to pass sensitive information through Docker Secrets
.
For this purpose, any secret whose name is similar to the name of an
environment variable is considered as an environment variable:
version: "3.3"
services:
orthanc-with-direct-secret:
image: osimis/orthanc
depends_on: [index-db]
ports: ["8003:8042"]
environment:
ORTHANC__NAME: "orthanc-with-direct-secret"
VERBOSE_ENABLED: "true"
OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED: "true"
ORTHANC__POSTGRESQL__HOST: "index-db"
ORTHANC__REGISTERED_USERS: |
{"demo": "demo"}
secrets:
- ORTHANC__POSTGRESQL__PASSWORD
secrets:
ORTHANC__POSTGRESQL__PASSWORD:
file: ORTHANC__POSTGRESQL__PASSWORD
Parts of your configuration can be defined in a configuration file, another part in an environment variable and yet another in a secret. If the same setting is defined in multiple location, the latest one will overwrite the first. Settings are evaluated in this order:
/etc/orthanc/
/run/secrets
(Docker secrets are copied there
by Docker)At this point, if some settings have not been defined yet, some defaults are applied (see below).
Orthanc and each plugin might have some default settings that might eventually be different from the defaults included in the Orthanc executable or the plugin library.
Orthanc non-standard defaults:
{
"StorageDirectory" : "/var/lib/orthanc/db",
"RemoteAccessAllowed": true,
"AuthenticationEnabled": true,
"HttpsCACertificates" : "/etc/ssl/certs/ca-certificates.crt",
"Plugins" : ["/usr/share/orthanc/plugins/"]
}
Some Lua scripts are already loaded in the image but are not configured to
be loaded by Orthanc automatically. You’ll have to add them to the "LuaScripts"
configuration if you want to use them.
/lua-scripts/filter-http-tools-reset.lua
can be used to regenerate the /tmp/orthanc.json
configuration file that is loaded by Orthanc every time
you POST to /tools/reset
. Note that it declares an IncomingHttpRequestFilter
callback that might conflict with your scripts.
Plugins are automatically enabled as soon as you define a setting
in their JSON section or as soon as you define to true
their
specific environment variable.
Below is a list of all plugins, their environment variable and their default configuration (only when their default configuration is different from the plugin defaults):
Plugin | Environment variable | Default configuration |
---|---|---|
Authorization | AUTHORIZATION_PLUGIN_ENABLED |
|
ConnectivityChecks | CONNECTIVITY_CHECKS_PLUGIN_ENABLED |
|
DicomWeb | DICOM_WEB_PLUGIN_ENABLED |
{
"DicomWeb": {
"Enable": true
}
}
|
Gdcm | GDCM_PLUGIN_ENABLED
Note: enabled by default |
{
"Gdcm": {
"Throttling": 4,
"RestrictTransferSyntaxes": [
"1.2.840.10008.1.2.4.90",
"1.2.840.10008.1.2.4.91",
"1.2.840.10008.1.2.4.92",
"1.2.840.10008.1.2.4.93"
]
}
}
|
OrthancWebViewer | ORTHANC_WEB_VIEWER_PLUGIN_ENABLED |
|
StoneWebViewer | ORTHANC_STONE_VIEWER_PLUGIN_ENABLED |
|
OsimisWebViewerBasic | OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED |
|
OsimisWebViewerBasicAlpha | OSIMIS_WEB_VIEWER1_ALPHA_PLUGIN_ENABLED |
|
PostgreSQL | POSTGRESQL_PLUGIN_ENABLED |
{
"PostgreSQL": {
"EnableIndex": true,
"EnableStorage": false,
"Port": 5432,
"Host": "HOST MUST BE DEFINED",
"Database": "postgres",
"Username": "postgres",
"Password": "postgres",
"EnableSsl": false,
"Lock": false
}
}
|
MySQL | MYSQL_PLUGIN_ENABLED |
{
"MySQL": {
"EnableIndex": true,
"EnableStorage": false,
"Port": 3306,
"Host": "HOST MUST BE DEFINED",
"Database": "mysql",
"Username": "root",
"Password": "mysql",
"Lock": false
}
}
|
Python | PYTHON_PLUGIN_ENABLED |
|
ServeFolders | SERVE_FOLDERS_PLUGIN_ENABLED |
|
Transfers | TRANSFERS_PLUGIN_ENABLED |
|
Worklists | WORKLISTS_PLUGIN_ENABLED |
{
"Worklists": {
"Enable": true,
"Database": "/var/lib/orthanc/worklists"
}
}
|
Whole-slide imaging | WSI_PLUGIN_ENABLED |
|
Osimis cloud (synchronization plugin) | OSIMIS_CLOUD_PLUGIN_ENABLED |
The source code that is used to generate the image can be found here.
The Python script that is used at startup can be found here