Mercurial > hg > orthanc-book
annotate Sphinx/source/users/docker-osimis.rst @ 478:f7ad03a214fe
ce
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Thu, 06 Aug 2020 09:18:15 +0200 |
| parents | 982774ebee52 |
| children | 9c5263c89272 |
| rev | line source |
|---|---|
| 393 | 1 .. _docker-osimis: |
| 2 .. highlight:: bash | |
| 3 | |
| 4 | |
| 5 Osimis Orthanc Docker images | |
| 6 ============================ | |
| 7 | |
| 8 .. contents:: | |
| 9 :depth: 3 | |
| 10 | |
| 11 | |
| 400 | 12 .. warning:: This documentation applies to ``osimis/orthanc`` images from the ``20.4.2`` version. |
| 13 | |
| 14 Note that these images have been re-written in April 2020. The documentation | |
| 15 for older images is still available `here <https://osimis.atlassian.net/wiki/spaces/OKB/pages/26738689/How+to+use+osimis+orthanc+Docker+images#Howtouseosimis/orthancDockerimages>`__ | |
| 16 | |
| 17 The new images are backward compatible with the previous images except for the | |
| 18 Google Cloud Platform configuration. | |
| 19 | |
| 20 However, if you're still using legacy environment variables, you'll get some warning | |
| 21 encouraging you to update to the new namings since the backward compatibility | |
| 22 might be removed one day (currently planed in June 2021). | |
| 23 | |
| 393 | 24 |
| 25 Introduction | |
| 26 ------------ | |
| 27 | |
| 28 Our commercial partner `Osimis <https://www.osimis.io>`__ | |
| 29 `publishes separated Docker images | |
| 30 <https://hub.docker.com/repository/docker/osimis/orthanc>`__ | |
| 31 that are used by their technical team in order to provide professional | |
| 32 support to their customers. | |
| 33 | |
| 34 These images have been designed to be used with ``docker-compose`` and | |
| 35 provide a configuration system through: | |
| 36 | |
| 37 - environment variables | |
| 38 - Docker secrets | |
| 39 - classical configuration files | |
| 40 - a mix of these options | |
| 41 | |
| 42 This `repository <https://bitbucket.org/osimis/orthanc-setup-samples/src>`__ | |
| 43 contains lots of examples on how to use these images. In particular, | |
| 401 | 44 `this example <https://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/all-usages/docker-compose.yml>`__ |
| 393 | 45 shows all the way that can be used to generate the same |
| 46 configuration in Orthanc. | |
| 47 | |
| 48 | |
| 49 Environmnent variables | |
| 50 ---------------------- | |
| 51 | |
| 52 Any part of the Orthanc configuration file can be configured through an | |
| 53 environment variable. Now that Orthanc and its plugins have hundreds of | |
| 54 configuration parameter, listing all these environment variable would be | |
| 55 too long. That's why we have defined a standard way of naming the variable: | |
| 56 | |
| 57 +---------------------------+----------------------------------------------+----------------------------------------------------------------+ | |
| 58 | Orthanc configuration | Environment variable | Sample value | | |
| 59 +===========================+==============================================+================================================================+ | |
| 60 | StableAge | ORTHANC__STABLE_AGE | ``30`` | | |
| 61 +---------------------------+----------------------------------------------+----------------------------------------------------------------+ | |
| 62 | DicomWeb.Root | ORTHANC__DICOM_WEB__ROOT | ``/dicom-web/`` | | |
| 63 +---------------------------+----------------------------------------------+----------------------------------------------------------------+ | |
| 64 | DicomWeb.Servers | ORTHANC__DICOM_WEB__SERVERS | ``{"sample": [ "http://127.0.0.1/dicom-web/"]}`` | | |
| 65 +---------------------------+----------------------------------------------+----------------------------------------------------------------+ | |
| 66 | |
| 398 | 67 To find out an environment variable name from an Orthanc setting |
| 393 | 68 (i.e. ``DicomWeb.StudiesMetadata`` is the ``path`` to a setting): |
| 69 | |
| 70 - everytime a word contains a capital letter, insert an underscore ``_`` in front. | |
| 71 ``DicomWeb.StudiesMetadata`` now becomes ``Dicom_Web.Studies_Metadata`` | |
| 72 - everytime you go down one level in the json configuration, insert | |
| 73 a double underscore ``__``. ``Dicom_Web.Studies_Metadata`` now becomes | |
| 74 ``Dicom_Web__Studies_Metadata`` | |
| 75 - capitalize all letters. ``Dicom_Web__Studies_Metadata`` now becomes | |
| 76 ``DICOM_WEB__STUDIES_METADATA`` | |
| 77 - add ``ORTHANC__`` in front. ``DICOM_WEB__STUDIES_METADATA`` now becomes | |
| 78 ``ORTHANC__DICOM_WEB__STUDIES_METADATA`` | |
| 79 | |
| 395 | 80 Note that, this automatic rule might fail because of 2 capital letters one after each other in some |
| 400 | 81 Orthanc settings. Therefore, there are some `exceptions <https://bitbucket.org/osimis/orthanc-builder/src/master/docker/orthanc/env-var-non-standards.json>`__ to this rule |
| 395 | 82 that are however quite intuitive. |
| 393 | 83 |
| 84 Special environment variables | |
| 85 ----------------------------- | |
| 86 | |
| 87 Other environment variables are not related to the Orthanc configuration file | |
| 88 but can be specified to control the way Orthanc is run. | |
| 89 | |
| 90 - ``VERBOSE_STARTUP=true`` will allow you to debug the startup process and see | |
| 91 the configuration that has been provided to Orthanc. This setup should be | |
| 92 disabled in production since it might display secret information like passwords | |
| 93 in your logs | |
| 94 - ``VERBOSE_ENABLED=true`` will start Orthanc with the ``--verbose`` option | |
| 95 - ``TRACE_ENABLED=true`` will start Orthanc with the ``--trace`` option | |
| 96 - ``NO_JOBS=true`` will start Orthanc with the ``--no-jobs`` option | |
| 97 - ``UNLOCK=true`` will start Orthanc with the ``--unlock`` option | |
| 98 - ``MALLOC_ARENA_MAX=10`` will :ref:`control memory usage <scalability-memory>` | |
| 395 | 99 - ``ORTHANC_JSON`` can be used to pass a json "root" configuration (see below). |
| 393 | 100 |
| 101 Configuration files | |
| 102 ------------------- | |
| 103 | |
| 104 .. highlight:: yaml | |
| 105 | |
| 106 Configuration files should be stored in the ``/etc/orthanc/`` folder inside the Docker image. | |
| 107 This is done by building an image thanks to a ``Dockerfile``:: | |
| 108 | |
| 109 FROM osimis/orthanc | |
| 110 COPY orthanc.json /etc/orthanc/ | |
| 111 | |
| 112 | |
| 113 Configuration files can also be passed as secrets as shown in this ``docker-compose.yml``:: | |
| 114 | |
| 115 version: "3.3" | |
| 116 services: | |
| 117 orthanc-file-in-secrets: | |
| 118 image: osimis/orthanc | |
| 119 depends_on: [index-db] | |
| 120 ports: ["8201:8042"] | |
| 121 environment: | |
| 122 VERBOSE_STARTUP: "true" | |
| 123 | |
| 124 secrets: | |
| 125 - orthanc.secret.json | |
| 126 | |
| 127 secrets: | |
| 128 orthanc.secret.json: | |
| 129 file: orthanc.secret.json | |
| 130 | |
| 131 Finaly, a whole configuration file can be passed as a JSON through the ``ORTHANC_JSON`` environment variable:: | |
| 132 | |
| 133 version: "3.3" | |
| 134 services: | |
| 135 orthanc-file-in-env-var: | |
| 136 image: osimis/orthanc | |
| 137 depends_on: [index-db] | |
| 138 ports: ["8200:8042"] | |
| 139 environment: | |
| 140 VERBOSE_ENABLED: "true" | |
| 141 OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED: "true" | |
| 142 | |
| 143 ORTHANC_JSON: | | |
| 144 { | |
| 145 "Name": "orthanc-file-in-env-var", | |
| 146 "PostgreSQL" : { | |
| 147 "Host": "index-db", | |
| 148 "Password": "pg-password" | |
| 149 }, | |
| 150 "RegisteredUsers": { | |
| 151 "demo": "demo" | |
| 152 } | |
| 153 } | |
| 154 | |
| 155 | |
| 156 Docker secrets | |
| 157 -------------- | |
| 158 | |
| 159 .. highlight:: yaml | |
| 160 | |
| 161 When using your container in a ``Docker Swarm`` or ``Kubernetes`` environment, | |
| 398 | 162 it is usually advised to pass sensitive information through ``Docker Secrets``. |
| 393 | 163 For this purpose, any secret whose name is similar to the name of an |
| 164 environment variable is considered as an environment variable:: | |
| 165 | |
| 166 version: "3.3" | |
| 167 services: | |
| 168 orthanc-with-direct-secret: | |
| 169 image: osimis/orthanc | |
| 170 depends_on: [index-db] | |
| 171 ports: ["8003:8042"] | |
| 172 environment: | |
| 173 ORTHANC__NAME: "orthanc-with-direct-secret" | |
| 174 VERBOSE_ENABLED: "true" | |
| 175 | |
| 176 OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED: "true" | |
| 177 | |
| 178 ORTHANC__POSTGRESQL__HOST: "index-db" | |
| 179 ORTHANC__REGISTERED_USERS: | | |
| 180 {"demo": "demo"} | |
| 181 | |
| 182 secrets: | |
| 183 - ORTHANC__POSTGRESQL__PASSWORD | |
| 184 secrets: | |
| 185 ORTHANC__POSTGRESQL__PASSWORD: | |
| 186 file: ORTHANC__POSTGRESQL__PASSWORD | |
| 187 | |
| 188 | |
| 189 Mixing configuration | |
| 190 -------------------- | |
| 191 | |
| 192 Parts of your configuration can be defined in a configuration file, | |
| 193 another part in an environment variable and yet another in a secret. | |
| 194 If the same setting is defined in multiple location, the latest one | |
| 195 will overwrite the first. Settings are evaluated in this order: | |
| 196 | |
| 197 - JSON files from ``/etc/orthanc/`` | |
| 198 - JSON files from ``/run/secrets`` (Docker secrets are copied there | |
| 199 by Docker) | |
| 200 - environment variables | |
| 201 - secret environment variables | |
| 202 | |
| 203 At this point, if some settings have not been defined yet, some defaults | |
| 204 are applied (see below). | |
| 205 | |
| 206 | |
| 207 Default configuration | |
| 208 --------------------- | |
| 209 | |
| 210 .. highlight:: json | |
| 211 | |
| 212 Orthanc and each plugin might have some default settings that might | |
| 213 eventually be different from the defaults included in the Orthanc | |
| 214 executable or the plugin library. | |
| 215 | |
| 216 .. below json is copied from orthanc-builder/docker/orthanc/orthanc-defaults.json | |
| 217 | |
| 218 Orthanc non-standard defaults:: | |
| 219 | |
| 220 { | |
| 221 "StorageDirectory" : "/var/lib/orthanc/db", | |
| 222 | |
| 223 "RemoteAccessAllowed": true, | |
| 224 "AuthenticationEnabled": true, | |
| 225 | |
| 226 "HttpsCACertificates" : "/etc/ssl/certs/ca-certificates.crt", | |
| 227 | |
| 228 "Plugins" : ["/usr/share/orthanc/plugins/"] | |
| 229 } | |
| 230 | |
| 231 | |
| 232 Plugins | |
| 233 ------- | |
| 234 | |
| 235 Plugins are automatically enabled as soon as you define a setting | |
| 236 in their JSON section or as soon as you define to ``true`` their | |
| 237 specific environment variable. | |
| 238 | |
| 418 | 239 Below is a list of all plugins, their environment variable and their default configuration |
| 240 (only when their default configuration is different from the plugin defaults): | |
| 393 | 241 |
| 242 | |
| 243 .. below table is obtained by running orthanc-builder/docker/orthanc/generatePluginDoc.py | |
| 244 | |
| 245 | |
| 246 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
| 247 | Plugin | Environment variable | Default configuration | | |
| 457 | 248 +==================================================+==================================================+====================================================================================================+ |
| 249 | **Authorization** | ``AUTHORIZATION_PLUGIN_ENABLED`` | | | |
| 393 | 250 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ |
| 457 | 251 | **ConnectivityChecks** | ``CONNECTIVITY_CHECKS_PLUGIN_ENABLED`` | | |
| 252 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
| 253 | **DicomWeb** | ``DICOM_WEB_PLUGIN_ENABLED`` | .. code-block:: json | | |
| 254 | | | | | |
| 255 | | | { | | |
| 393 | 256 | | | "DicomWeb": { | |
| 257 | | | "Enable": true | | |
| 457 | 258 | | | } | |
| 259 | | | } | | |
| 260 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
| 261 | **Gdcm** | ``GDCM_PLUGIN_ENABLED`` | .. code-block:: json | | |
| 262 | | Note: enabled by default | | | |
| 263 | | | { | | |
| 264 | | | "Gdcm": { | | |
| 265 | | | "Throttling": 4, | | |
| 266 | | | "RestrictTransferSyntaxes": [ | | |
| 267 | | | "1.2.840.10008.1.2.4.90", | | |
| 268 | | | "1.2.840.10008.1.2.4.91", | | |
| 269 | | | "1.2.840.10008.1.2.4.92", | | |
| 270 | | | "1.2.840.10008.1.2.4.93" | | |
| 271 | | | ] | | |
| 272 | | | } | | |
| 393 | 273 | | | } | |
| 274 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
| 275 | **OrthancWebViewer** | ``ORTHANC_WEB_VIEWER_PLUGIN_ENABLED`` | | | |
| 457 | 276 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ |
| 277 | **OsimisWebViewerBasic** | ``OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED`` | | | |
| 278 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
| 279 | **OsimisWebViewerBasicAlpha** | ``OSIMIS_WEB_VIEWER1_ALPHA_PLUGIN_ENABLED`` | | | |
| 280 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
| 281 | **PostgreSQL** | ``POSTGRESQL_PLUGIN_ENABLED`` | .. code-block:: json | | |
| 282 | | | | | |
| 283 | | | { | | |
| 284 | | | "PostgreSQL": { | | |
| 285 | | | "EnableIndex": true, | | |
| 286 | | | "EnableStorage": false, | | |
| 287 | | | "Port": 5432, | | |
| 288 | | | "Host": "HOST MUST BE DEFINED", | | |
| 289 | | | "Database": "postgres", | | |
| 290 | | | "Username": "postgres", | | |
|
417
47d772aa7b3e
added Gdcm entry for osimis/orthanc docker images
Alain Mazy <alain@mazy.be>
parents:
401
diff
changeset
|
291 | | | "Password": "postgres", | |
| 457 | 292 | | | "EnableSsl": false, | |
| 293 | | | "Lock": false | | |
| 294 | | | } | | |
| 295 | | | } | | |
| 296 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
| 297 | **MySQL** | ``MYSQL_PLUGIN_ENABLED`` | .. code-block:: json | | |
|
417
47d772aa7b3e
added Gdcm entry for osimis/orthanc docker images
Alain Mazy <alain@mazy.be>
parents:
401
diff
changeset
|
298 | | | | |
| 457 | 299 | | | { | |
| 300 | | | "MySQL": { | | |
| 301 | | | "EnableIndex": true, | | |
| 302 | | | "EnableStorage": false, | | |
| 303 | | | "Port": 3306, | | |
| 304 | | | "Host": "HOST MUST BE DEFINED", | | |
| 305 | | | "Database": "mysql", | | |
| 306 | | | "Username": "root", | | |
| 307 | | | "Password": "mysql", | | |
| 308 | | | "Lock": false | | |
| 309 | | | } | | |
| 310 | | | } | | |
| 311 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
| 312 | **Python** | ``PYTHON_PLUGIN_ENABLED`` | | | |
| 313 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
| 314 | **ServeFolders** | ``SERVE_FOLDERS_PLUGIN_ENABLED`` | | | |
| 315 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
| 316 | **Transfers** | ``TRANSFERS_PLUGIN_ENABLED`` | | | |
| 317 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
| 318 | **Worklists** | ``WORKLISTS_PLUGIN_ENABLED`` | .. code-block:: json | | |
| 319 | | | | | |
| 320 | | | { | | |
| 321 | | | "Worklists": { | | |
| 322 | | | "Enable": true, | | |
| 323 | | | "Database": "/var/lib/orthanc/worklists" | | |
| 324 | | | } | | |
| 325 | | | } | | |
| 326 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
| 327 | **Wsi** | ``WSI_PLUGIN_ENABLED`` | | | |
| 328 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | |
|
417
47d772aa7b3e
added Gdcm entry for osimis/orthanc docker images
Alain Mazy <alain@mazy.be>
parents:
401
diff
changeset
|
329 |
| 395 | 330 Under the hood |
| 331 -------------- | |
| 332 | |
| 400 | 333 The source code that is used to generate the image can be found `here <https://bitbucket.org/osimis/orthanc-builder/src/master/docker/orthanc/Dockerfile>`__. |
| 395 | 334 |
| 400 | 335 The python script that is used at startup can be found `here <https://bitbucket.org/osimis/orthanc-builder/src/master/docker/orthanc/generateConfiguration.py>`__ |