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