|
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>`__
|
|
|
39
|
|
|
40 Environmnent variables
|
|
|
41 ----------------------
|
|
|
42
|
|
|
43 Any part of the Orthanc configuration file can be configured through an
|
|
|
44 environment variable. Now that Orthanc and its plugins have hundreds of
|
|
|
45 configuration parameter, listing all these environment variable would be
|
|
|
46 too long. That's why we have defined a standard way of naming the variable:
|
|
|
47
|
|
|
48 +---------------------------+----------------------------------------------+----------------------------------------------------------------+
|
|
|
49 | Orthanc configuration | Environment variable | Sample value |
|
|
|
50 +===========================+==============================================+================================================================+
|
|
|
51 | StableAge | ORTHANC__STABLE_AGE | ``30`` |
|
|
|
52 +---------------------------+----------------------------------------------+----------------------------------------------------------------+
|
|
|
53 | DicomWeb.Root | ORTHANC__DICOM_WEB__ROOT | ``/dicom-web/`` |
|
|
|
54 +---------------------------+----------------------------------------------+----------------------------------------------------------------+
|
|
|
55 | DicomWeb.Servers | ORTHANC__DICOM_WEB__SERVERS | ``{"sample": [ "http://127.0.0.1/dicom-web/"]}`` |
|
|
|
56 +---------------------------+----------------------------------------------+----------------------------------------------------------------+
|
|
|
57
|
|
|
58 To find out a environment variable name from an Orthanc configuration
|
|
|
59 (i.e. ``DicomWeb.StudiesMetadata`` is the ``path`` to a setting):
|
|
|
60
|
|
|
61 - everytime a word contains a capital letter, insert an underscore ``_`` in front.
|
|
|
62 ``DicomWeb.StudiesMetadata`` now becomes ``Dicom_Web.Studies_Metadata``
|
|
|
63 - everytime you go down one level in the json configuration, insert
|
|
|
64 a double underscore ``__``. ``Dicom_Web.Studies_Metadata`` now becomes
|
|
|
65 ``Dicom_Web__Studies_Metadata``
|
|
|
66 - capitalize all letters. ``Dicom_Web__Studies_Metadata`` now becomes
|
|
|
67 ``DICOM_WEB__STUDIES_METADATA``
|
|
|
68 - add ``ORTHANC__`` in front. ``DICOM_WEB__STUDIES_METADATA`` now becomes
|
|
|
69 ``ORTHANC__DICOM_WEB__STUDIES_METADATA``
|
|
|
70
|
|
|
71
|
|
|
72 Special environment variables
|
|
|
73 -----------------------------
|
|
|
74
|
|
|
75 Other environment variables are not related to the Orthanc configuration file
|
|
|
76 but can be specified to control the way Orthanc is run.
|
|
|
77
|
|
|
78 - ``VERBOSE_STARTUP=true`` will allow you to debug the startup process and see
|
|
|
79 the configuration that has been provided to Orthanc. This setup should be
|
|
|
80 disabled in production since it might display secret information like passwords
|
|
|
81 in your logs
|
|
|
82 - ``VERBOSE_ENABLED=true`` will start Orthanc with the ``--verbose`` option
|
|
|
83 - ``TRACE_ENABLED=true`` will start Orthanc with the ``--trace`` option
|
|
|
84 - ``NO_JOBS=true`` will start Orthanc with the ``--no-jobs`` option
|
|
|
85 - ``UNLOCK=true`` will start Orthanc with the ``--unlock`` option
|
|
|
86 - ``MALLOC_ARENA_MAX=10`` will :ref:`control memory usage <scalability-memory>`
|
|
|
87
|
|
|
88
|
|
|
89 Configuration files
|
|
|
90 -------------------
|
|
|
91
|
|
|
92 .. highlight:: yaml
|
|
|
93
|
|
|
94 Configuration files should be stored in the ``/etc/orthanc/`` folder inside the Docker image.
|
|
|
95 This is done by building an image thanks to a ``Dockerfile``::
|
|
|
96
|
|
|
97 FROM osimis/orthanc
|
|
|
98 COPY orthanc.json /etc/orthanc/
|
|
|
99
|
|
|
100
|
|
|
101 Configuration files can also be passed as secrets as shown in this ``docker-compose.yml``::
|
|
|
102
|
|
|
103 version: "3.3"
|
|
|
104 services:
|
|
|
105 orthanc-file-in-secrets:
|
|
|
106 image: osimis/orthanc
|
|
|
107 depends_on: [index-db]
|
|
|
108 ports: ["8201:8042"]
|
|
|
109 environment:
|
|
|
110 VERBOSE_STARTUP: "true"
|
|
|
111
|
|
|
112 secrets:
|
|
|
113 - orthanc.secret.json
|
|
|
114
|
|
|
115 secrets:
|
|
|
116 orthanc.secret.json:
|
|
|
117 file: orthanc.secret.json
|
|
|
118
|
|
|
119 Finaly, a whole configuration file can be passed as a JSON through the ``ORTHANC_JSON`` environment variable::
|
|
|
120
|
|
|
121 version: "3.3"
|
|
|
122 services:
|
|
|
123 orthanc-file-in-env-var:
|
|
|
124 image: osimis/orthanc
|
|
|
125 depends_on: [index-db]
|
|
|
126 ports: ["8200:8042"]
|
|
|
127 environment:
|
|
|
128 VERBOSE_ENABLED: "true"
|
|
|
129 OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED: "true"
|
|
|
130
|
|
|
131 ORTHANC_JSON: |
|
|
|
132 {
|
|
|
133 "Name": "orthanc-file-in-env-var",
|
|
|
134 "PostgreSQL" : {
|
|
|
135 "Host": "index-db",
|
|
|
136 "Password": "pg-password"
|
|
|
137 },
|
|
|
138 "RegisteredUsers": {
|
|
|
139 "demo": "demo"
|
|
|
140 }
|
|
|
141 }
|
|
|
142
|
|
|
143
|
|
|
144 Docker secrets
|
|
|
145 --------------
|
|
|
146
|
|
|
147 .. highlight:: yaml
|
|
|
148
|
|
|
149 When using your container in a ``Docker Swarm`` or ``Kubernetes`` environment,
|
|
|
150 it is usually to pass sensitive information through ``Docker Secrets``.
|
|
|
151 For this purpose, any secret whose name is similar to the name of an
|
|
|
152 environment variable is considered as an environment variable::
|
|
|
153
|
|
|
154 version: "3.3"
|
|
|
155 services:
|
|
|
156 orthanc-with-direct-secret:
|
|
|
157 image: osimis/orthanc
|
|
|
158 depends_on: [index-db]
|
|
|
159 ports: ["8003:8042"]
|
|
|
160 environment:
|
|
|
161 ORTHANC__NAME: "orthanc-with-direct-secret"
|
|
|
162 VERBOSE_ENABLED: "true"
|
|
|
163
|
|
|
164 OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED: "true"
|
|
|
165
|
|
|
166 ORTHANC__POSTGRESQL__HOST: "index-db"
|
|
|
167 ORTHANC__REGISTERED_USERS: |
|
|
|
168 {"demo": "demo"}
|
|
|
169
|
|
|
170 secrets:
|
|
|
171 - ORTHANC__POSTGRESQL__PASSWORD
|
|
|
172 secrets:
|
|
|
173 ORTHANC__POSTGRESQL__PASSWORD:
|
|
|
174 file: ORTHANC__POSTGRESQL__PASSWORD
|
|
|
175
|
|
|
176
|
|
|
177 Mixing configuration
|
|
|
178 --------------------
|
|
|
179
|
|
|
180 Parts of your configuration can be defined in a configuration file,
|
|
|
181 another part in an environment variable and yet another in a secret.
|
|
|
182 If the same setting is defined in multiple location, the latest one
|
|
|
183 will overwrite the first. Settings are evaluated in this order:
|
|
|
184
|
|
|
185 - JSON files from ``/etc/orthanc/``
|
|
|
186 - JSON files from ``/run/secrets`` (Docker secrets are copied there
|
|
|
187 by Docker)
|
|
|
188 - environment variables
|
|
|
189 - secret environment variables
|
|
|
190
|
|
|
191 At this point, if some settings have not been defined yet, some defaults
|
|
|
192 are applied (see below).
|
|
|
193
|
|
|
194
|
|
|
195 Default configuration
|
|
|
196 ---------------------
|
|
|
197
|
|
|
198 .. highlight:: json
|
|
|
199
|
|
|
200 Orthanc and each plugin might have some default settings that might
|
|
|
201 eventually be different from the defaults included in the Orthanc
|
|
|
202 executable or the plugin library.
|
|
|
203
|
|
|
204 .. below json is copied from orthanc-builder/docker/orthanc/orthanc-defaults.json
|
|
|
205
|
|
|
206 Orthanc non-standard defaults::
|
|
|
207
|
|
|
208 {
|
|
|
209 "StorageDirectory" : "/var/lib/orthanc/db",
|
|
|
210
|
|
|
211 "RemoteAccessAllowed": true,
|
|
|
212 "AuthenticationEnabled": true,
|
|
|
213
|
|
|
214 "HttpsCACertificates" : "/etc/ssl/certs/ca-certificates.crt",
|
|
|
215
|
|
|
216 "Plugins" : ["/usr/share/orthanc/plugins/"]
|
|
|
217 }
|
|
|
218
|
|
|
219
|
|
|
220 Plugins
|
|
|
221 -------
|
|
|
222
|
|
|
223 Plugins are automatically enabled as soon as you define a setting
|
|
|
224 in their JSON section or as soon as you define to ``true`` their
|
|
|
225 specific environment variable.
|
|
|
226
|
|
|
227 Below is a list of all plugins, their environment variable and their default configuration:
|
|
|
228
|
|
|
229
|
|
|
230 .. below table is obtained by running orthanc-builder/docker/orthanc/generatePluginDoc.py
|
|
|
231
|
|
|
232
|
|
|
233 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
|
234 | Plugin | Environment variable | Default configuration |
|
|
|
235 +==================================================+==================================================+====================================================================================================+
|
|
|
236 | **Authorization** | ``AUTHORIZATION_PLUGIN_ENABLED`` | |
|
|
|
237 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
|
238 | **ConnectivityChecks** | ``CONNECTIVITY_CHECKS_PLUGIN_ENABLED`` | |
|
|
|
239 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
|
240 | **DicomWeb** | ``DICOM_WEB_PLUGIN_ENABLED`` | .. code-block:: json |
|
|
|
241 | | | |
|
|
|
242 | | | { |
|
|
|
243 | | | "DicomWeb": { |
|
|
|
244 | | | "Enable": true |
|
|
|
245 | | | } |
|
|
|
246 | | | } |
|
|
|
247 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
|
248 | **GoogleCloudPlatform** | ``GOOGLE_CLOUD_PLATFORM_PLUGIN_ENABLED`` | |
|
|
|
249 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
|
250 | **OrthancWebViewer** | ``ORTHANC_WEB_VIEWER_PLUGIN_ENABLED`` | |
|
|
|
251 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
|
252 | **OsimisWebViewerBasic** | ``OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED`` | |
|
|
|
253 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
|
254 | **OsimisWebViewerBasicAlpha** | ``OSIMIS_WEB_VIEWER1_ALPHA_PLUGIN_ENABLED`` | |
|
|
|
255 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
|
256 | **PostgreSQL** | ``POSTGRESQL_PLUGIN_ENABLED`` | .. code-block:: json |
|
|
|
257 | | | |
|
|
|
258 | | | { |
|
|
|
259 | | | "PostgreSQL": { |
|
|
|
260 | | | "EnableIndex": true, |
|
|
|
261 | | | "EnableStorage": false, |
|
|
|
262 | | | "Port": 5432, |
|
|
|
263 | | | "Host": "HOST MUST BE DEFINED", |
|
|
|
264 | | | "Database": "postgres", |
|
|
|
265 | | | "Username": "postgres", |
|
|
|
266 | | | "Password": "postgres", |
|
|
|
267 | | | "EnableSsl": false, |
|
|
|
268 | | | "Lock": false |
|
|
|
269 | | | } |
|
|
|
270 | | | } |
|
|
|
271 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
|
272 | **ServeFolders** | ``SERVE_FOLDERS_PLUGIN_ENABLED`` | |
|
|
|
273 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
|
274 | **Transfers** | ``TRANSFERS_PLUGIN_ENABLED`` | |
|
|
|
275 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
|
276 | **Worklists** | ``WORKLISTS_PLUGIN_ENABLED`` | .. code-block:: json |
|
|
|
277 | | | |
|
|
|
278 | | | { |
|
|
|
279 | | | "Worklists": { |
|
|
|
280 | | | "Enable": true, |
|
|
|
281 | | | "Database": "/var/lib/orthanc/worklists" |
|
|
|
282 | | | } |
|
|
|
283 | | | } |
|
|
|
284 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+
|
|
|
285 | **Wsi** | ``WSI_PLUGIN_ENABLED`` | |
|
|
|
286 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ |
