Mercurial > hg > orthanc-book
annotate Sphinx/source/users/docker.rst @ 1113:a588960a72e5 default tip
spelling
| author | Alain Mazy <am@orthanc.team> |
|---|---|
| date | Mon, 28 Oct 2024 09:23:08 +0100 |
| parents | 689c27b34bd6 |
| children |
| rev | line source |
|---|---|
| 54 | 1 .. _docker: |
| 2 .. highlight:: bash | |
| 3 | |
| 4 | |
|
882
815f70009ec2
highlight osimis/orthanc docker images since jodogne/orthanc images are currently not up-to-date
Alain Mazy <am@osimis.io>
parents:
866
diff
changeset
|
5 jodogne/orthanc Docker images |
|
815f70009ec2
highlight osimis/orthanc docker images since jodogne/orthanc images are currently not up-to-date
Alain Mazy <am@osimis.io>
parents:
866
diff
changeset
|
6 ============================= |
| 54 | 7 |
|
481
4f076a3b9934
unanswered-forum.rst
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
8 .. toctree:: |
|
4f076a3b9934
unanswered-forum.rst
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
9 :hidden: |
|
4f076a3b9934
unanswered-forum.rst
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
10 |
|
1023
5d4701d8fe28
replaced osimis/orthanc by orthancteam/orthanc
Alain Mazy <am@osimis.io>
parents:
1021
diff
changeset
|
11 docker-orthancteam.rst |
|
481
4f076a3b9934
unanswered-forum.rst
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
12 |
|
4f076a3b9934
unanswered-forum.rst
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
13 |
| 54 | 14 .. contents:: |
| 15 :depth: 3 | |
| 16 | |
| 17 | |
| 18 Introduction | |
| 19 ------------ | |
| 20 | |
| 21 `Docker images <https://en.wikipedia.org/wiki/Docker_(software)>`__ | |
| 22 for the Orthanc core and its official plugins are freely available on | |
| 23 the `DockerHub platform <https://hub.docker.com/u/jodogne/>`__. The | |
| 24 source code of the corresponding Docker images is available on `GitHub | |
| 25 <https://github.com/jodogne/OrthancDocker>`__. | |
| 26 | |
| 1102 | 27 |
| 28 .. _docker-jodogne-vs-orthanc-team: | |
| 29 | |
| 1109 | 30 ``jodogne/orthanc`` vs. ``orthancteam/orthanc`` Docker images |
| 31 ------------------------------------------------------------- | |
| 1102 | 32 |
| 33 Two different flavors of Docker images for Orthanc are available: | |
| 229 | 34 |
| 1109 | 35 * The ``jodogne/orthanc`` and ``jodogne/orthanc-plugins`` Docker images that are |
| 36 described on this page are regularly kept in sync with the latest releases of | |
| 37 the Orthanc project, with a basic configuration system that is inherited from | |
| 38 the Debian packages (i.e., manual edition of the configuration files). | |
| 39 | |
| 40 This is also where the new experimental features from `Sébastien Jodogne's | |
| 41 research team at UCLouvain <https://orthanc.uclouvain.be/>`__ are initially | |
| 42 released. The binaries used in these images correspond to the Linux Standard | |
| 43 Base binaries. | |
| 44 | |
| 45 The default user interface is the built-in **Orthanc Explorer**. | |
| 46 | |
| 47 These images are most useful to **software developers and researchers**. | |
| 229 | 48 |
|
1027
60b0b7ea409b
migration to orthancteam
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1023
diff
changeset
|
49 * Our commercial partner `Orthanc Team <https://orthanc.team/>`__ also |
| 1102 | 50 `publishes separate Docker images |
| 1109 | 51 <https://hub.docker.com/r/orthancteam/orthanc>`__. |
| 52 | |
| 53 These ``orthancteam/orthanc`` images are released 2 or 3 times a month every | |
| 54 time a new version of a plugin or Orthanc is available or every time the base | |
| 55 Debian image needs to be updated for security reasons. | |
| 56 | |
| 57 Each image has a tag and the `list of each component version is documented | |
| 58 <https://hub.docker.com/r/orthancteam/orthanc>`__. | |
| 59 | |
| 60 These images support both AMD64 and ARM64 architectures. | |
| 61 | |
| 62 These images can be configured using congirutation files or **environment | |
| 63 variables** (which is very handy if using Docker Compose or Kubernetes). | |
| 64 | |
| 65 The default user interface is the **Orthanc Explorer 2** :ref:`plugin | |
| 66 <orthanc-explorer-2>`. | |
| 67 | |
| 68 These images are targeted at **ops teams and end-users**. | |
| 69 | |
| 70 A :ref:`specific page <docker-orthancteam>` is available to describe how these | |
| 71 images should be used. | |
| 229 | 72 |
| 73 **Note for CentOS users:** The Docker environment might be difficult to | |
| 54 | 74 configure on your platform. Hints are available on the `Orthanc Users |
| 75 discussion group | |
| 76 <https://groups.google.com/d/msg/orthanc-users/w-uPAknnRQc/-XhzBGSCAwAJ>`__. | |
| 77 | |
| 78 | |
| 79 Running the Orthanc core | |
| 80 ------------------------ | |
| 81 | |
| 82 The following command will start the core of Orthanc, with all the | |
| 83 plugins disabled:: | |
| 84 | |
|
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
85 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc |
| 54 | 86 |
| 87 Once Orthanc is running, use Mozilla Firefox at URL | |
| 88 http://localhost:8042/ to interact with Orthanc. The default username | |
| 89 is ``orthanc`` and its password is ``orthanc``. | |
| 90 | |
| 91 The command above starts the mainline version of Orthanc, whose | |
| 69 | 92 development is in continuous progress. Do not forget to regularly |
| 93 update the Docker image to benefit from the latest features:: | |
| 94 | |
|
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
95 $ docker pull jodogne/orthanc |
| 69 | 96 |
| 97 If more stability is required, you can select the official release of | |
| 98 Orthanc to be run:: | |
| 54 | 99 |
| 1075 | 100 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc:1.12.4 |
| 54 | 101 |
| 102 Passing additional command-line options (e.g. to make Orthanc verbose) | |
| 103 can be done as follows (note the ``/etc/orthanc`` option that is | |
| 104 required for Orthanc to find its configuration files):: | |
| 105 | |
| 1075 | 106 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc:1.12.4 /etc/orthanc --verbose |
| 54 | 107 |
| 108 | |
| 109 Usage, with plugins enabled | |
| 110 --------------------------- | |
| 111 | |
| 112 The following command will run the mainline version of the Orthanc | |
| 113 core, together with its :ref:`Web viewer <webviewer>`, its | |
| 114 :ref:`PostgreSQL support <postgresql>`, its :ref:`DICOMweb | |
| 115 implementation <dicomweb>`, and its :ref:`whole-slide imaging viewer | |
| 116 <wsi>`:: | |
| 117 | |
|
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
118 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-plugins |
| 54 | 119 |
| 365 | 120 Or you can also start a specific version of Orthanc for more stability:: |
| 121 | |
| 1075 | 122 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-plugins:1.12.4 |
| 365 | 123 |
|
364
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
363
diff
changeset
|
124 If you have an interest in the :ref:`Python plugin <python-plugin>`, |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
363
diff
changeset
|
125 you can use the ``orthanc-python`` image. The latter image is a |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
363
diff
changeset
|
126 heavier version of the ``orthanc-plugins`` image, as it embeds the |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
363
diff
changeset
|
127 Python 3.7 interpreter. Here is how to start this image:: |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
363
diff
changeset
|
128 |
| 365 | 129 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-python |
| 1075 | 130 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-python:1.12.4 |
|
364
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
363
diff
changeset
|
131 |
| 54 | 132 |
| 133 Fine-tuning the configuration | |
| 134 ----------------------------- | |
| 135 | |
| 136 For security reasons, you should at least protect your instance of | |
| 137 Orthanc by changing this default user, in the ``RegisteredUsers`` | |
| 138 :ref:`configuration option <configuration>`. You will also probably | |
| 139 need to fine-tune other parameters, notably the list of the DICOM | |
| 140 modalities Orthanc knows about. | |
| 141 | |
| 142 You can generate a custom configuration file for Orthanc as follows:: | |
| 143 | |
| 1075 | 144 $ docker run --rm --entrypoint=cat jodogne/orthanc:1.12.4 /etc/orthanc/orthanc.json > /tmp/orthanc.json |
| 54 | 145 |
| 146 Then, edit the just-generated file ``/tmp/orthanc.json`` and restart | |
| 147 Orthanc with your updated configuration:: | |
| 148 | |
| 1075 | 149 $ docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro jodogne/orthanc:1.12.4 |
| 54 | 150 |
|
384
e4b0a4d69f42
note about memory usage
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
382
diff
changeset
|
151 *Remark:* These Docker images automatically set the environment |
|
e4b0a4d69f42
note about memory usage
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
382
diff
changeset
|
152 variable ``MALLOC_ARENA_MAX`` to ``5`` in order to :ref:`control |
|
e4b0a4d69f42
note about memory usage
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
382
diff
changeset
|
153 memory usage <scalability-memory>`. This default setting can be |
|
e4b0a4d69f42
note about memory usage
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
382
diff
changeset
|
154 overriden by providing the option ``-e MALLOC_ARENA_MAX=1`` when |
| 386 | 155 invoking ``docker run`` (the value ``0`` corresponds to the default |
| 156 value). | |
|
384
e4b0a4d69f42
note about memory usage
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
382
diff
changeset
|
157 |
| 54 | 158 |
| 382 | 159 .. _docker-compose: |
| 160 | |
| 161 Configuration management using Docker Compose | |
| 162 --------------------------------------------- | |
| 163 | |
| 164 Depending on the context, the `Docker Compose tool | |
| 165 <https://docs.docker.com/compose/>`__ might be easier to use than the | |
| 166 plain Docker tool, as it allows replacing long command lines as above, | |
| 167 by plain configuration files. The trick here is to provide the JSON | |
| 168 configuration files to Orthanc as `secrets | |
| 169 <https://docs.docker.com/compose/compose-file/#secrets>`__ (note that | |
| 170 the related option ``configs`` could in theory be better, | |
| 171 unfortunately it is only available to `Docker Swarm | |
| 172 <https://github.com/docker/compose/issues/5110>`__). | |
| 173 | |
|
673
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
174 .. highlight:: yaml |
| 382 | 175 |
| 176 First create the ``docker-compose.yml`` file as follows (this one uses | |
| 177 the `YAML file format <https://en.wikipedia.org/wiki/YAML>`__):: | |
| 178 | |
| 179 version: '3.1' # Secrets are only available since this version of Docker Compose | |
| 180 services: | |
| 181 orthanc: | |
| 1075 | 182 image: jodogne/orthanc-plugins:1.12.4 |
| 382 | 183 command: /run/secrets/ # Path to the configuration files (stored as secrets) |
| 184 ports: | |
| 402 | 185 - 4242:4242 |
| 382 | 186 - 8042:8042 |
| 187 secrets: | |
|
673
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
188 - orthanc.json |
|
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
189 environment: |
|
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
190 - ORTHANC_NAME=HelloWorld |
| 382 | 191 secrets: |
| 192 orthanc.json: | |
| 193 file: orthanc.json | |
| 194 | |
| 195 .. highlight:: json | |
| 196 | |
| 197 Then, place the configuration file ``orthanc.json`` next to the | |
| 198 ``docker-compose.yml`` file. Here is a minimalist ``orthanc.json``:: | |
| 199 | |
| 200 { | |
|
673
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
201 "Name" : "${ORTHANC_NAME} in Docker Compose", |
| 382 | 202 "RemoteAccessAllowed" : true |
| 203 } | |
| 204 | |
| 205 .. highlight:: bash | |
| 206 | |
| 207 This single configuration file should contain all the required | |
| 208 configuration options for Orthanc and all its plugins. The container | |
| 209 can then be started as follows:: | |
| 210 | |
| 211 $ docker-compose up | |
| 212 | |
|
673
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
213 Note how the `environment variable |
|
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
214 <https://docs.docker.com/compose/environment-variables/>`__ |
|
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
215 ``ORTHANC_NAME`` has been used in order to easily adapt the |
|
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
216 configuration of Orthanc. This results from the fact that Orthanc |
|
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
217 injects :ref:`environment variables <orthanc-environment-variables>` |
|
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
218 once reading the content of its configuration files (since Orthanc |
|
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
219 1.5.0). |
| 382 | 220 |
|
673
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
221 |
| 54 | 222 Making the Orthanc database persistent |
| 223 -------------------------------------- | |
| 224 | |
| 225 The filesystem of Docker containers is volatile (its content is | |
| 226 deleted once the container stops). You can make the Orthanc database | |
| 227 persistent by mapping the ``/var/lib/orthanc/db`` folder of the | |
| 228 container to some path in the filesystem of your Linux host, e.g.:: | |
| 229 | |
| 230 $ mkdir /tmp/orthanc-db | |
| 1075 | 231 $ docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc-db/:/var/lib/orthanc/db/ jodogne/orthanc:1.12.4 |
| 54 | 232 |
| 233 | |
| 234 Whole-slide imaging support | |
| 235 --------------------------- | |
| 236 | |
| 237 The ``orthanc-plugins`` image includes support for :ref:`microscopic | |
| 238 whole-slide imaging (WSI) <wsi>`. For instance, the following command | |
| 239 will start the WSI viewer plugin transparently together with Orthanc:: | |
| 240 | |
| 1075 | 241 $ docker run -p 4242:4242 -p 8042:8042 --rm --name orthanc-wsi jodogne/orthanc-plugins:1.12.4 |
| 54 | 242 |
| 243 Note that we gave the name ``orthanc-wsi`` to this new Docker | |
| 244 container. Then, the Dicomizer command-line tool can be invoked as | |
| 245 follows:: | |
| 246 | |
| 1075 | 247 $ docker run -t -i --rm --link=orthanc-wsi:orthanc --entrypoint=OrthancWSIDicomizer -v /tmp/Source.tif:/tmp/Source.tif:ro jodogne/orthanc-plugins:1.12.4 --username=orthanc --password=orthanc --orthanc=http://orthanc:8042/ /tmp/Source.tif |
| 54 | 248 |
| 249 This command needs a few explanations: | |
| 250 | |
| 251 * ``--link=orthanc-wsi:orthanc`` links the container running the | |
| 252 Dicomizer, to the Docker container running Orthanc that we started | |
| 253 just before. | |
| 254 * ``--entrypoint=OrthancWSIDicomizer`` specifies that the Dicomizer | |
| 255 must be run instead of the Orthanc server. | |
| 256 * ``-v /tmp/Source.tif:/tmp/Source.tif:ro`` maps the source image | |
| 257 ``/tmp/Source.tif`` on the host computer into the Orthanc container | |
| 258 as read-only file ``/tmp/Source.tif``. | |
| 259 * ``--orthanc=http://orthanc:8042/`` instructs the Dicomizer to push | |
| 260 images through the ``--link`` created above. | |
| 261 * ``--username=orthanc --password=orthanc`` correspond to the default | |
| 262 credentials of the ``orthanc-plugins`` image. | |
| 263 | |
| 264 Obviously, you are free to add all the options you wish (check out the | |
| 265 ``--help`` flag to list these options). In particular, the | |
| 266 ``--dataset`` option allows to specify DICOM tags, in the JSON file | |
| 267 format, so as to include them in the resulting DICOM series (the | |
| 268 option ``--sample-dataset`` prints a sample JSON file that has the | |
| 269 expected format). | |
| 270 | |
| 271 If you have a source image that is not a hierarchical TIFF, you must | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
272 instruct the Dicomizer to use `OpenSlide <https://openslide.org/>`__ |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
273 to decode it by adding the ``--openslide`` option:: |
| 54 | 274 |
| 1075 | 275 $ docker run -t -i --rm --link=orthanc-wsi:orthanc --entrypoint=OrthancWSIDicomizer -v /tmp/Source.svs:/tmp/Source.svs:ro jodogne/orthanc-plugins:1.12.4 --username=orthanc --password=orthanc --orthanc=http://orthanc:8042/ --openslide=libopenslide.so /tmp/Source.svs |
| 54 | 276 |
| 277 | |
| 278 PostgreSQL and Orthanc inside Docker | |
| 279 ------------------------------------ | |
| 280 | |
| 281 It is possible to run both Orthanc and PostgreSQL inside Docker. First, start the official PostgreSQL container:: | |
| 282 | |
|
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
283 $ docker run --name some-postgres -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=pgpassword --rm postgres |
| 54 | 284 |
| 285 Open another shell, and create a database to host the Orthanc database:: | |
| 286 | |
|
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
287 $ docker run -it --link some-postgres:postgres --rm postgres sh -c 'echo "CREATE DATABASE orthanc;" | exec psql -h "$POSTGRES_PORT_5432_TCP_ADDR" -p "$POSTGRES_PORT_5432_TCP_PORT" -U postgres' |
| 54 | 288 |
| 289 You will have to type the password (cf. the environment variable | |
| 290 ``POSTGRES_PASSWORD`` above that it set to ``pgpassword``). Then, | |
| 291 retrieve the IP and the port of the PostgreSQL container, together | |
| 292 with the default Orthanc configuration file:: | |
| 293 | |
|
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
294 $ docker inspect --format '{{ .NetworkSettings.IPAddress }}' some-postgres |
|
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
295 $ docker inspect --format '{{ .NetworkSettings.Ports }}' some-postgres |
| 1075 | 296 $ docker run --rm --entrypoint=cat jodogne/orthanc-plugins:1.12.4 /etc/orthanc/orthanc.json > /tmp/orthanc.json |
| 54 | 297 |
|
673
767c2550fa00
environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
298 .. highlight:: text |
| 54 | 299 |
| 300 Add the following section to ``/tmp/orthanc.json`` (adapting the | |
| 301 values Host and Port to what docker inspect said above):: | |
| 302 | |
| 303 "PostgreSQL" : { | |
| 304 "EnableIndex" : true, | |
| 305 "EnableStorage" : true, | |
| 306 "Host" : "172.17.0.38", | |
| 307 "Port" : 5432, | |
| 308 "Database" : "orthanc", | |
| 309 "Username" : "postgres", | |
| 310 "Password" : "pgpassword" | |
| 311 } | |
| 312 | |
| 313 .. highlight:: bash | |
| 314 | |
| 315 Finally, you can start Orthanc:: | |
| 316 | |
| 1075 | 317 $ docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro jodogne/orthanc-plugins:1.12.4 |
| 54 | 318 |
| 319 | |
| 320 Debugging | |
| 321 --------- | |
| 322 | |
| 176 | 323 .. highlight:: text |
| 324 | |
| 54 | 325 For debugging purpose, you can start an interactive bash session as |
| 326 follows:: | |
| 327 | |
| 1075 | 328 $ docker run -i -t --rm --entrypoint=bash jodogne/orthanc:1.12.4 |
| 329 $ docker run -i -t --rm --entrypoint=bash jodogne/orthanc-plugins:1.12.4 |