Mercurial > hg > orthanc-book

comparison Sphinx/source/users/docker-osimis.rst @ 393:43c5a1274740

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc for osimis/orthanc images
author Alain Mazy <alain@mazy.be>
date Tue, 21 Apr 2020 15:23:50 +0200
parents
children d44f6f93a987
comparison
equal deleted inserted replaced
391:4bc6bcd83ae5 393:43c5a1274740
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 +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+