Mercurial > hg > orthanc-book

comparison Sphinx/source/users/docker-orthancteam.rst @ 1023:5d4701d8fe28

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
replaced osimis/orthanc by orthancteam/orthanc
author Alain Mazy <am@osimis.io>
date Thu, 01 Feb 2024 15:09:48 +0100
parents
children 16e4ee083319
comparison
equal deleted inserted replaced
1022:2969cbebbc91 1023:5d4701d8fe28
1 .. _docker-orthancteam:
2 .. highlight:: bash
3
4
5 orthancteam/orthanc Docker images
6 =================================
7
8 .. contents::
9 :depth: 3
10
11 .. warning::
12 Starting from February 2024, the ``osimis/orthanc`` Docker images have been renamed
13 into ``orthancteam/orthanc``. The ``osimis/orthanc`` images won't be updated anymore
14 therefore you should switch to the ``orthancteam/orthanc`` images.
15
16 Note that all old tags released prior to February 2024 have been copied into ``orthancteam/orthanc``
17 as well so, even if you are using an old version, you should update the name in your setup.
18 The name is the only thing that has changed. The content and build procedure are identical.
19
20 .. warning::
21
22 Starting from the ``22.6.1`` release, we are providing 2 types of images:
23
24 - the default image with the usual tag: e.g ``22.6.1``
25 - the full image with a e.g ``22.6.1-full`` tag
26
27 The default image is suitable for 99.9% of users.
28
29 You should use the full image only if you need to use one of these:
30
31 - the Azure Blob storage plugin
32 - the Google Cloud storage plugin
33 - the ODBC plugin with SQL Server (msodbcsql18 is preinstalled)
34
35
36 Introduction
37 ------------
38
39 Our commercial partner `Orthanc Team <https://orthanc.team>`__
40 `publishes separated Docker images
41 <https://hub.docker.com/r/orthancteam/orthanc>`__.
42 These images have been designed to be used with ``docker-compose`` and
43 provide a configuration system through:
44
45 - environment variables
46 - Docker secrets
47 - classical configuration files
48 - a mix of these options
49
50 This `repository <https://github.com/orthanc-server/orthanc-setup-samples/src>`__
51 contains lots of examples on how to use these images. In particular,
52 `this example <https://github.com/orthanc-server/orthanc-setup-samples/tree/master/docker/all-usages/docker-compose.yml>`__
53 shows all the way that can be used to generate the same
54 configuration in Orthanc.
55
56
57 Environment variables
58 ---------------------
59
60 Any part of the Orthanc configuration file can be configured through an
61 environment variable. Now that Orthanc and its plugins have hundreds of
62 configuration parameter, listing all these environment variable would be
63 too long. That's why we have defined a standard way of naming the variable:
64
65 +---------------------------+----------------------------------------------+----------------------------------------------------------------+
66 | Orthanc configuration | Environment variable | Sample value |
67 +===========================+==============================================+================================================================+
68 | StableAge | ORTHANC__STABLE_AGE | ``30`` |
69 +---------------------------+----------------------------------------------+----------------------------------------------------------------+
70 | DicomWeb.Root | ORTHANC__DICOM_WEB__ROOT | ``/dicom-web/`` |
71 +---------------------------+----------------------------------------------+----------------------------------------------------------------+
72 | DicomWeb.Servers | ORTHANC__DICOM_WEB__SERVERS | ``{"sample": [ "http://127.0.0.1/dicom-web/"]}`` |
73 +---------------------------+----------------------------------------------+----------------------------------------------------------------+
74
75 To find out an environment variable name from an Orthanc setting
76 (i.e. ``DicomWeb.StudiesMetadata`` is the ``path`` to a setting):
77
78 - whenever a word contains a capital letter, insert an underscore ``_`` in front.
79 ``DicomWeb.StudiesMetadata`` now becomes ``Dicom_Web.Studies_Metadata``
80 - whenever you go down one level in the JSON configuration, insert
81 a double underscore ``__``. ``Dicom_Web.Studies_Metadata`` now becomes
82 ``Dicom_Web__Studies_Metadata``
83 - capitalize all letters. ``Dicom_Web__Studies_Metadata`` now becomes
84 ``DICOM_WEB__STUDIES_METADATA``
85 - add ``ORTHANC__`` in front. ``DICOM_WEB__STUDIES_METADATA`` now becomes
86 ``ORTHANC__DICOM_WEB__STUDIES_METADATA``
87
88 Note that, this automatic rule might fail because of 2 capital letters one after each other in some
89 Orthanc settings. Therefore, there are some `exceptions <https://github.com/orthanc-server/orthanc-builder/blob/master/docker/orthanc/env-var-non-standards.json>`__ to this rule
90 that are however quite intuitive.
91
92 Special environment variables
93 -----------------------------
94
95 Other environment variables are not related to the Orthanc configuration file
96 but can be specified to control the way Orthanc is run.
97
98 - ``VERBOSE_STARTUP=true`` will allow you to debug the startup process and see
99 the configuration that has been provided to Orthanc. This setup should be
100 disabled in production since it might display secret information like passwords
101 in your logs
102 - ``VERBOSE_ENABLED=true`` will start Orthanc with the ``--verbose`` option
103 - ``TRACE_ENABLED=true`` will start Orthanc with the ``--trace`` option
104 - ``NO_JOBS=true`` will start Orthanc with the ``--no-jobs`` option
105 - ``LOGDIR=/logs`` will start Orthanc with the ``--logdir=/logs`` option (introduced in 21.9.1)
106 - ``LOGFILE=/logs`` will start Orthanc with the ``--logfile=/logs/orthanc.log`` option (introduced in 21.9.1)
107 - ``MALLOC_ARENA_MAX=10`` will :ref:`control memory usage <scalability-memory>`
108 - ``ORTHANC_JSON`` can be used to pass a JSON "root" configuration (see below).
109 - ``BEFORE_ORTHANC_STARTUP_SCRIPT`` can be used to `run a custom script <https://groups.google.com/g/orthanc-users/c/EXjTq2ZU1vw/m/02CwW1jzAQAJ>`__ before starting Orthanc.
110 - ``FORCE_HOST_ID`` and ``GENERATE_HOST_ID_IF_MISSING`` can be used to control the content of /etc/hostid (introduced in 22.9.1).
111 DCMTK calls gethostid() when generating DICOM UIDs (used, e.g, in modifications/anonymizations).
112 When /etc/hostid is missing, the system tries to generate it from the IP of the system.
113 On some system, in particular circumstances, we have observed that the system performs a DNS query
114 to get the IP of the system. This DNS can timeout (after multiple with retries) and, in particular cases,
115 we have observed a delay of 40 seconds to generate a single DICOM UID in Orthanc.
116 Therefore, if /etc/hostid is missing, the startup script creates it and fill it with a random number (default behaviour).
117 This behaviour can still be deactivated by defining ``GENERATE_HOST_ID_IF_MISSING=false``.
118 The host id can also be forced by defining ``FORCE_HOST_ID``.
119
120
121
122 Configuration files
123 -------------------
124
125 .. highlight:: yaml
126
127 Configuration files should be stored in the ``/etc/orthanc/`` folder inside the Docker image.
128 This is done by building an image thanks to a ``Dockerfile``::
129
130 FROM orthancteam/orthanc
131 COPY orthanc.json /etc/orthanc/
132
133
134 Configuration files can also be passed as secrets as shown in this ``docker-compose.yml``::
135
136 version: "3.3"
137 services:
138 orthanc-file-in-secrets:
139 image: orthancteam/orthanc
140 depends_on: [index-db]
141 ports: ["8201:8042"]
142 environment:
143 VERBOSE_STARTUP: "true"
144
145 secrets:
146 - orthanc.secret.json
147
148 secrets:
149 orthanc.secret.json:
150 file: orthanc.secret.json
151
152 Finally, a whole configuration file can be passed as a JSON through the ``ORTHANC_JSON`` environment variable::
153
154 version: "3.3"
155 services:
156 orthanc-file-in-env-var:
157 image: orthancteam/orthanc
158 depends_on: [index-db]
159 ports: ["8200:8042"]
160 environment:
161 VERBOSE_ENABLED: "true"
162 OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED: "true"
163
164 ORTHANC_JSON: |
165 {
166 "Name": "orthanc-file-in-env-var",
167 "PostgreSQL" : {
168 "Host": "index-db",
169 "Password": "pg-password"
170 },
171 "RegisteredUsers": {
172 "demo": "demo"
173 }
174 }
175
176
177 Docker secrets
178 --------------
179
180 .. highlight:: yaml
181
182 When using your container in a ``Docker Swarm`` or ``Kubernetes`` environment,
183 it is usually advised to pass sensitive information through ``Docker Secrets``.
184 For this purpose, any secret whose name is similar to the name of an
185 environment variable is considered as an environment variable::
186
187 version: "3.3"
188 services:
189 orthanc-with-direct-secret:
190 image: orthancteam/orthanc
191 depends_on: [index-db]
192 ports: ["8003:8042"]
193 environment:
194 ORTHANC__NAME: "orthanc-with-direct-secret"
195 VERBOSE_ENABLED: "true"
196
197 OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED: "true"
198
199 ORTHANC__POSTGRESQL__HOST: "index-db"
200 ORTHANC__REGISTERED_USERS: |
201 {"demo": "demo"}
202
203 secrets:
204 - ORTHANC__POSTGRESQL__PASSWORD
205 secrets:
206 ORTHANC__POSTGRESQL__PASSWORD:
207 file: ORTHANC__POSTGRESQL__PASSWORD
208
209
210 Mixing configuration
211 --------------------
212
213 Parts of your configuration can be defined in a configuration file,
214 another part in an environment variable and yet another in a secret.
215 If the same setting is defined in multiple location, the latest one
216 will overwrite the first. Settings are evaluated in this order:
217
218 - JSON files from ``/etc/orthanc/``
219 - JSON files from ``/run/secrets`` (Docker secrets are copied there
220 by Docker)
221 - environment variables
222 - secret environment variables
223
224 At this point, if some settings have not been defined yet, some defaults
225 are applied (see below).
226
227
228 Default configuration
229 ---------------------
230
231 .. highlight:: json
232
233 Orthanc and each plugin might have some default settings that might
234 eventually be different from the defaults included in the Orthanc
235 executable or the plugin library.
236
237 .. below json is copied from orthanc-builder/docker/orthanc/orthanc-defaults.json
238
239 Orthanc non-standard defaults::
240
241 {
242 "StorageDirectory" : "/var/lib/orthanc/db",
243
244 "RemoteAccessAllowed": true,
245 "AuthenticationEnabled": true,
246
247 "HttpsCACertificates" : "/etc/ssl/certs/ca-certificates.crt",
248
249 "Plugins" : ["/usr/share/orthanc/plugins/"]
250 }
251
252
253 Default Lua scripts
254 -------------------
255
256 Some Lua scripts are already loaded in the image but are not configured to
257 be loaded by Orthanc automatically. You'll have to add them to the ``"LuaScripts"``
258 configuration if you want to use them.
259
260 `/lua-scripts/filter-http-tools-reset.lua <https://github.com/orthanc-server/orthanc-builder/blob/master/docker/orthanc/filter-http-tools-reset.lua>`__
261 can be used to regenerate the ``/tmp/orthanc.json`` configuration file that is loaded by Orthanc every time
262 you POST to ``/tools/reset``. Note that it declares an ``IncomingHttpRequestFilter``
263 callback that might conflict with your scripts.
264
265 Healthcheck probe
266 -----------------
267
268 In version 21.10.0, the `/probes/test-aliveness.py <https://github.com/orthanc-server/orthanc-builder/blob/master/docker/orthanc/test-aliveness.py>`__
269 script has been added in order to perform healthchecks. Check the doc in the script itself for more details.
270 A sample configuration is also available in `this sample <https://github.com/orthanc-server/orthanc-setup-samples/src/8016d140a237a892db703aac4782307c46732847/docker/tls-mutual-auth/docker-compose.yml#lines-51>`__
271
272
273 Plugins
274 -------
275
276 Plugins are automatically enabled as soon as you define a setting
277 in their JSON section or as soon as you define to ``true`` their
278 specific environment variable.
279
280 Below is a list of all plugins, their environment variable and their default configuration
281 (only when their default configuration is different from the plugin defaults):
282
283
284 .. below table is obtained by running orthanc-builder/docker/orthanc/generatePluginDoc.py
285
286
287 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
288 | Plugin | Environment variable | Default configuration |
289 +==================================================+==================================================+====================================================================================================+
290 | **Authorization** | ``AUTHORIZATION_PLUGIN_ENABLED`` | |
291 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
292 | **ConnectivityChecks** | ``CONNECTIVITY_CHECKS_PLUGIN_ENABLED`` | |
293 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
294 | **DicomWeb** | ``DICOM_WEB_PLUGIN_ENABLED`` | .. code-block:: json |
295 | | | |
296 | | | { |
297 | | | "DicomWeb": { |
298 | | | "Enable": true |
299 | | | } |
300 | | | } |
301 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
302 | **Gdcm** | ``GDCM_PLUGIN_ENABLED`` | .. code-block:: json |
303 | | Note: enabled by default | |
304 | | | { |
305 | | | "Gdcm": { |
306 | | | "Throttling": 4, |
307 | | | "RestrictTransferSyntaxes": [ |
308 | | | "1.2.840.10008.1.2.4.90", |
309 | | | "1.2.840.10008.1.2.4.91", |
310 | | | "1.2.840.10008.1.2.4.92", |
311 | | | "1.2.840.10008.1.2.4.93" |
312 | | | ] |
313 | | | } |
314 | | | } |
315 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
316 | **OrthancWebViewer** | ``ORTHANC_WEB_VIEWER_PLUGIN_ENABLED`` | |
317 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
318 | **StoneWebViewer** | ``STONE_WEB_VIEWER_PLUGIN_ENABLED`` | |
319 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
320 | **OsimisWebViewerBasic** | ``OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED`` | |
321 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
322 | **OsimisWebViewerBasicAlpha** | ``OSIMIS_WEB_VIEWER1_ALPHA_PLUGIN_ENABLED`` | |
323 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
324 | **PostgreSQL** | ``POSTGRESQL_PLUGIN_ENABLED`` | .. code-block:: json |
325 | | | |
326 | | | { |
327 | | | "PostgreSQL": { |
328 | | | "EnableIndex": true, |
329 | | | "EnableStorage": false, |
330 | | | "Port": 5432, |
331 | | | "Host": "HOST MUST BE DEFINED", |
332 | | | "Database": "postgres", |
333 | | | "Username": "postgres", |
334 | | | "Password": "postgres", |
335 | | | "EnableSsl": false, |
336 | | | "Lock": false |
337 | | | } |
338 | | | } |
339 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
340 | **MySQL** | ``MYSQL_PLUGIN_ENABLED`` | .. code-block:: json |
341 | | | |
342 | | | { |
343 | | | "MySQL": { |
344 | | | "EnableIndex": true, |
345 | | | "EnableStorage": false, |
346 | | | "Port": 3306, |
347 | | | "Host": "HOST MUST BE DEFINED", |
348 | | | "Database": "mysql", |
349 | | | "Username": "root", |
350 | | | "Password": "mysql", |
351 | | | "Lock": false |
352 | | | } |
353 | | | } |
354 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
355 | **Python** | ``PYTHON_PLUGIN_ENABLED`` | |
356 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
357 | **ServeFolders** | ``SERVE_FOLDERS_PLUGIN_ENABLED`` | |
358 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
359 | **Transfers** | ``TRANSFERS_PLUGIN_ENABLED`` | |
360 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
361 | **Worklists** | ``WORKLISTS_PLUGIN_ENABLED`` | .. code-block:: json |
362 | | | |
363 | | | { |
364 | | | "Worklists": { |
365 | | | "Enable": true, |
366 | | | "Database": "/var/lib/orthanc/worklists" |
367 | | | } |
368 | | | } |
369 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
370 | **Housekeeper** | ``HOUSEKEEPER_PLUGIN_ENABLED`` | .. code-block:: json |
371 | | | |
372 | | | { |
373 | | | "Housekeeper": { |
374 | | | "Enable": true |
375 | | | } |
376 | | | } |
377 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
378 | **DelayedDeletion** | ``DELAYED_DELETION_PLUGIN_ENABLED`` | .. code-block:: json |
379 | | | |
380 | | | { |
381 | | | "DelayedDeletion": { |
382 | | | "Enable": true |
383 | | | } |
384 | | | } |
385 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
386 | **MultitenantDicom** | ``MULTITENANT_DICOM_PLUGIN_ENABLED`` | |
387 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
388 | **Wsi** | ``WSI_PLUGIN_ENABLED`` | |
389 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
390 | **Odbc** | ``ODBC_PLUGIN_ENABLED`` | .. code-block:: json |
391 | | | |
392 | | | { |
393 | | | "Odbc": { |
394 | | | "EnableIndex": true, |
395 | | | "EnableStorage": false, |
396 | | | "IndexConnectionString": "MUST BE DEFINED", |
397 | | | "StorageConnectionString": "MUST BE DEFINED" |
398 | | | } |
399 | | | } |
400 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
401 | **Tcia** | ``TCIA_PLUGIN_ENABLED`` | .. code-block:: json |
402 | | | |
403 | | | { |
404 | | | "Tcia": { |
405 | | | "Enable": true |
406 | | | } |
407 | | | } |
408 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
409 | **Indexer** | ``INDEXER_PLUGIN_ENABLED`` | .. code-block:: json |
410 | | | |
411 | | | { |
412 | | | "Indexer": { |
413 | | | "Enable": true |
414 | | | } |
415 | | | } |
416 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
417 | **Neuro** | ``NEURO_PLUGIN_ENABLED`` | .. code-block:: json |
418 | | | |
419 | | | { |
420 | | | "Neuro": { |
421 | | | "Enable": true |
422 | | | } |
423 | | | } |
424 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
425 | **AzureBlobStorage** | ``AZURE_BLOB_STORAGE_PLUGIN_ENABLED`` | .. code-block:: json |
426 | | | |
427 | | | { |
428 | | | "AzureBlobStorage": { |
429 | | | "ConnectionString": "MUST BE DEFINED BY YOU", |
430 | | | "ContainerName": "MUST BE DEFINED BY YOU" |
431 | | | } |
432 | | | } |
433 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
434 | **AwsS3Storage** | ``AWS_S3_STORAGE_PLUGIN_ENABLED`` | .. code-block:: json |
435 | | | |
436 | | | { |
437 | | | "AwsS3Storage": { |
438 | | | "BucketName": "MUST BE DEFINED BY YOU", |
439 | | | "Region": "MUST BE DEFINED BY YOU" |
440 | | | } |
441 | | | } |
442 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
443 | **GoogleCloudStorage** | ``GOOGLE_CLOUD_STORAGE_PLUGIN_ENABLED`` | .. code-block:: json |
444 | | | |
445 | | | { |
446 | | | "GoogleCloudStorage": { |
447 | | | "ServiceAccountFile": "MUST BE DEFINED BY YOU", |
448 | | | "BucketName": "MUST BE DEFINED BY YOU" |
449 | | | } |
450 | | | } |
451 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
452 | **OrthancExplorer2** | ``ORTHANC_EXPLORER_2_ENABLED`` | .. code-block:: json |
453 | | Note: enabled by default | |
454 | | | { |
455 | | | "OrthancExplorer2": { |
456 | | | "Enable": true, |
457 | | | "IsDefaultOrthancUI": false |
458 | | | } |
459 | | | } |
460 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
461 | **VolView** | ``VOLVIEW_PLUGIN_ENABLED`` | |
462 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
463 | **Ohif** | ``OHIF_PLUGIN_ENABLED`` | |
464 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
465
466
467 Under the hood
468 --------------
469
470 The source code that is used to generate the image can be found `here <https://github.com/orthanc-server/orthanc-builder/blob/master/docker/orthanc/Dockerfile>`__.
471
472 The Python script that is used at startup can be found `here <https://github.com/orthanc-server/orthanc-builder/blob/master/docker/orthanc/generateConfiguration.py>`__