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
|
|
239 Below is a list of all plugins, their environment variable and their default configuration:
|
|
240
|
|
241
|
|
242 .. below table is obtained by running orthanc-builder/docker/orthanc/generatePluginDoc.py
|
|
243
|
|
244
|
|
245 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
246 | Plugin | Environment variable | Default configuration |
|
|
247 +==================================================+==================================================+====================================================================================================+
|
|
248 | **Authorization** | ``AUTHORIZATION_PLUGIN_ENABLED`` | |
|
|
249 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
250 | **ConnectivityChecks** | ``CONNECTIVITY_CHECKS_PLUGIN_ENABLED`` | |
|
|
251 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
252 | **DicomWeb** | ``DICOM_WEB_PLUGIN_ENABLED`` | .. code-block:: json |
|
|
253 | | | |
|
|
254 | | | { |
|
|
255 | | | "DicomWeb": { |
|
|
256 | | | "Enable": true |
|
|
257 | | | } |
|
|
258 | | | } |
|
|
259 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
260 | **GoogleCloudPlatform** | ``GOOGLE_CLOUD_PLATFORM_PLUGIN_ENABLED`` | |
|
|
261 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
262 | **OrthancWebViewer** | ``ORTHANC_WEB_VIEWER_PLUGIN_ENABLED`` | |
|
|
263 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
264 | **OsimisWebViewerBasic** | ``OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED`` | |
|
|
265 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
266 | **OsimisWebViewerBasicAlpha** | ``OSIMIS_WEB_VIEWER1_ALPHA_PLUGIN_ENABLED`` | |
|
395
|
267 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
268 | **PostgreSQL** | ``POSTGRESQL_PLUGIN_ENABLED`` | .. code-block:: json |
|
|
269 | | | |
|
|
270 | | | { |
|
393
|
271 | | | "PostgreSQL": { |
|
395
|
272 | | | "EnableIndex": true, |
|
|
273 | | | "EnableStorage": false, |
|
|
274 | | | "Port": 5432, |
|
|
275 | | | "Host": "HOST MUST BE DEFINED", |
|
|
276 | | | "Database": "postgres", |
|
393
|
277 | | | "Username": "postgres", |
|
395
|
278 | | | "Password": "postgres", |
|
|
279 | | | "EnableSsl": false, |
|
|
280 | | | "Lock": false |
|
|
281 | | | } |
|
|
282 | | | } |
|
|
283 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
284 | **MySQL** | ``MYSQL_PLUGIN_ENABLED`` | .. code-block:: json |
|
|
285 | | | |
|
|
286 | | | { |
|
|
287 | | | "MySQL": { |
|
|
288 | | | "EnableIndex": true, |
|
|
289 | | | "EnableStorage": false, |
|
|
290 | | | "Port": 3306, |
|
|
291 | | | "Host": "HOST MUST BE DEFINED", |
|
|
292 | | | "Database": "mysql", |
|
|
293 | | | "Username": "root", |
|
|
294 | | | "Password": "mysql", |
|
|
295 | | | "Lock": false |
|
|
296 | | | } |
|
|
297 | | | } |
|
|
298 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
299 | **Python** | ``PYTHON_PLUGIN_ENABLED`` | |
|
|
300 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
301 | **ServeFolders** | ``SERVE_FOLDERS_PLUGIN_ENABLED`` | |
|
|
302 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
303 | **Transfers** | ``TRANSFERS_PLUGIN_ENABLED`` | |
|
|
304 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
305 | **Worklists** | ``WORKLISTS_PLUGIN_ENABLED`` | .. code-block:: json |
|
|
306 | | | |
|
|
307 | | | { |
|
|
308 | | | "Worklists": { |
|
|
309 | | | "Enable": true, |
|
|
310 | | | "Database": "/var/lib/orthanc/worklists" |
|
|
311 | | | } |
|
|
312 | | | } |
|
|
313 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
314 | **Wsi** | ``WSI_PLUGIN_ENABLED`` | |
|
|
315 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
316 Under the hood
|
|
317 --------------
|
|
318
|
400
|
319 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
|
320
|
400
|
321 The python script that is used at startup can be found `here <https://bitbucket.org/osimis/orthanc-builder/src/master/docker/orthanc/generateConfiguration.py>`__ |