Mercurial > hg > orthanc-book
annotate Sphinx/source/users/docker.rst @ 365:49202601d0c8
typo
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Tue, 31 Mar 2020 18:41:17 +0200 |
parents | 234de55ed125 |
children | 64b32cb19571 |
rev | line source |
---|---|
54 | 1 .. _docker: |
2 .. highlight:: bash | |
3 | |
4 | |
5 Orthanc for Docker | |
6 ================== | |
7 | |
8 .. contents:: | |
9 :depth: 3 | |
10 | |
11 | |
12 Introduction | |
13 ------------ | |
14 | |
15 `Docker images <https://en.wikipedia.org/wiki/Docker_(software)>`__ | |
16 for the Orthanc core and its official plugins are freely available on | |
17 the `DockerHub platform <https://hub.docker.com/u/jodogne/>`__. The | |
18 source code of the corresponding Docker images is available on `GitHub | |
19 <https://github.com/jodogne/OrthancDocker>`__. | |
20 | |
229 | 21 **Note about Orthanc vs. Osimis Docker images:** |
22 | |
23 * The ``jodogne/orthanc`` and ``jodogne/orthanc-plugins`` Docker | |
24 images that are described on this page are always kept in sync with | |
25 the latest releases of the Orthanc project, with a basic | |
26 configuration system that is inherited from the Debian packages | |
27 (i.e. manual edition of the configuration files). | |
28 | |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
29 * Our commercial partner `Osimis <https://www.osimis.io>`__ also |
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
30 `publishes separated Docker images |
229 | 31 <https://osimis.atlassian.net/wiki/spaces/OKB/pages/26738689/How+to+use+osimis+orthanc+Docker+images>`__. |
32 These ``osimis/orthanc`` images are used by the technical team of | |
33 Osimis in order to provide professional support to their customers, | |
34 with a configuration system that can be tuned through environment | |
35 variables (which is very handy if using ``docker-compose``). These | |
36 images are not necessarily always in sync with the Orthanc project, | |
37 but they also include the :ref:`plugins edited by Osimis | |
38 <plugins-osimis>`, notably the Osimis Web viewer (that is much more | |
39 advanced than the Orthanc Web viewer) and the advanced authorization | |
40 plugin. | |
41 | |
42 **Note for CentOS users:** The Docker environment might be difficult to | |
54 | 43 configure on your platform. Hints are available on the `Orthanc Users |
44 discussion group | |
45 <https://groups.google.com/d/msg/orthanc-users/w-uPAknnRQc/-XhzBGSCAwAJ>`__. | |
46 | |
47 | |
48 Running the Orthanc core | |
49 ------------------------ | |
50 | |
51 The following command will start the core of Orthanc, with all the | |
52 plugins disabled:: | |
53 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
54 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc |
54 | 55 |
56 Once Orthanc is running, use Mozilla Firefox at URL | |
57 http://localhost:8042/ to interact with Orthanc. The default username | |
58 is ``orthanc`` and its password is ``orthanc``. | |
59 | |
60 The command above starts the mainline version of Orthanc, whose | |
69 | 61 development is in continuous progress. Do not forget to regularly |
62 update the Docker image to benefit from the latest features:: | |
63 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
64 $ docker pull jodogne/orthanc |
69 | 65 |
66 If more stability is required, you can select the official release of | |
67 Orthanc to be run:: | |
54 | 68 |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
69 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc:1.6.0 |
54 | 70 |
71 Passing additional command-line options (e.g. to make Orthanc verbose) | |
72 can be done as follows (note the ``/etc/orthanc`` option that is | |
73 required for Orthanc to find its configuration files):: | |
74 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
75 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc /etc/orthanc --verbose |
54 | 76 |
77 | |
78 Usage, with plugins enabled | |
79 --------------------------- | |
80 | |
81 The following command will run the mainline version of the Orthanc | |
82 core, together with its :ref:`Web viewer <webviewer>`, its | |
83 :ref:`PostgreSQL support <postgresql>`, its :ref:`DICOMweb | |
84 implementation <dicomweb>`, and its :ref:`whole-slide imaging viewer | |
85 <wsi>`:: | |
86 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
87 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-plugins |
54 | 88 |
365 | 89 Or you can also start a specific version of Orthanc for more stability:: |
90 | |
91 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-plugins:1.6.0 | |
92 | |
364
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
363
diff
changeset
|
93 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
|
94 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
|
95 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
|
96 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
|
97 |
365 | 98 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-python |
99 $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-python:1.6.0 | |
364
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
363
diff
changeset
|
100 |
54 | 101 |
102 Fine-tuning the configuration | |
103 ----------------------------- | |
104 | |
105 For security reasons, you should at least protect your instance of | |
106 Orthanc by changing this default user, in the ``RegisteredUsers`` | |
107 :ref:`configuration option <configuration>`. You will also probably | |
108 need to fine-tune other parameters, notably the list of the DICOM | |
109 modalities Orthanc knows about. | |
110 | |
111 You can generate a custom configuration file for Orthanc as follows:: | |
112 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
113 $ docker run --rm --entrypoint=cat jodogne/orthanc /etc/orthanc/orthanc.json > /tmp/orthanc.json |
54 | 114 |
115 Then, edit the just-generated file ``/tmp/orthanc.json`` and restart | |
116 Orthanc with your updated configuration:: | |
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 -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro jodogne/orthanc |
54 | 119 |
120 | |
121 Making the Orthanc database persistent | |
122 -------------------------------------- | |
123 | |
124 The filesystem of Docker containers is volatile (its content is | |
125 deleted once the container stops). You can make the Orthanc database | |
126 persistent by mapping the ``/var/lib/orthanc/db`` folder of the | |
127 container to some path in the filesystem of your Linux host, e.g.:: | |
128 | |
129 $ mkdir /tmp/orthanc-db | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
130 $ docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc-db/:/var/lib/orthanc/db/ jodogne/orthanc:1.6.0 |
54 | 131 |
132 | |
133 Whole-slide imaging support | |
134 --------------------------- | |
135 | |
136 The ``orthanc-plugins`` image includes support for :ref:`microscopic | |
137 whole-slide imaging (WSI) <wsi>`. For instance, the following command | |
138 will start the WSI viewer plugin transparently together with Orthanc:: | |
139 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
140 $ docker run -p 4242:4242 -p 8042:8042 --rm --name orthanc-wsi jodogne/orthanc-plugins |
54 | 141 |
142 Note that we gave the name ``orthanc-wsi`` to this new Docker | |
143 container. Then, the Dicomizer command-line tool can be invoked as | |
144 follows:: | |
145 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
146 $ docker run -t -i --rm --link=orthanc-wsi:orthanc --entrypoint=OrthancWSIDicomizer -v /tmp/Source.tif:/tmp/Source.tif:ro jodogne/orthanc-plugins --username=orthanc --password=orthanc --orthanc=http://orthanc:8042/ /tmp/Source.tif |
54 | 147 |
148 This command needs a few explanations: | |
149 | |
150 * ``--link=orthanc-wsi:orthanc`` links the container running the | |
151 Dicomizer, to the Docker container running Orthanc that we started | |
152 just before. | |
153 * ``--entrypoint=OrthancWSIDicomizer`` specifies that the Dicomizer | |
154 must be run instead of the Orthanc server. | |
155 * ``-v /tmp/Source.tif:/tmp/Source.tif:ro`` maps the source image | |
156 ``/tmp/Source.tif`` on the host computer into the Orthanc container | |
157 as read-only file ``/tmp/Source.tif``. | |
158 * ``--orthanc=http://orthanc:8042/`` instructs the Dicomizer to push | |
159 images through the ``--link`` created above. | |
160 * ``--username=orthanc --password=orthanc`` correspond to the default | |
161 credentials of the ``orthanc-plugins`` image. | |
162 | |
163 Obviously, you are free to add all the options you wish (check out the | |
164 ``--help`` flag to list these options). In particular, the | |
165 ``--dataset`` option allows to specify DICOM tags, in the JSON file | |
166 format, so as to include them in the resulting DICOM series (the | |
167 option ``--sample-dataset`` prints a sample JSON file that has the | |
168 expected format). | |
169 | |
170 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
|
171 instruct the Dicomizer to use `OpenSlide <https://openslide.org/>`__ |
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
172 to decode it by adding the ``--openslide`` option:: |
54 | 173 |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
174 $ docker run -t -i --rm --link=orthanc-wsi:orthanc --entrypoint=OrthancWSIDicomizer -v /tmp/Source.svs:/tmp/Source.svs:ro jodogne/orthanc-plugins --username=orthanc --password=orthanc --orthanc=http://orthanc:8042/ --openslide=libopenslide.so /tmp/Source.svs |
54 | 175 |
176 | |
177 PostgreSQL and Orthanc inside Docker | |
178 ------------------------------------ | |
179 | |
180 It is possible to run both Orthanc and PostgreSQL inside Docker. First, start the official PostgreSQL container:: | |
181 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
182 $ docker run --name some-postgres -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=pgpassword --rm postgres |
54 | 183 |
184 Open another shell, and create a database to host the Orthanc database:: | |
185 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
186 $ 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 | 187 |
188 You will have to type the password (cf. the environment variable | |
189 ``POSTGRES_PASSWORD`` above that it set to ``pgpassword``). Then, | |
190 retrieve the IP and the port of the PostgreSQL container, together | |
191 with the default Orthanc configuration file:: | |
192 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
193 $ docker inspect --format '{{ .NetworkSettings.IPAddress }}' some-postgres |
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
194 $ docker inspect --format '{{ .NetworkSettings.Ports }}' some-postgres |
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
195 $ docker run --rm --entrypoint=cat jodogne/orthanc-plugins /etc/orthanc/orthanc.json > /tmp/orthanc.json |
54 | 196 |
197 .. highlight:: json | |
198 | |
199 Add the following section to ``/tmp/orthanc.json`` (adapting the | |
200 values Host and Port to what docker inspect said above):: | |
201 | |
202 "PostgreSQL" : { | |
203 "EnableIndex" : true, | |
204 "EnableStorage" : true, | |
205 "Host" : "172.17.0.38", | |
206 "Port" : 5432, | |
207 "Database" : "orthanc", | |
208 "Username" : "postgres", | |
209 "Password" : "pgpassword" | |
210 } | |
211 | |
212 .. highlight:: bash | |
213 | |
214 Finally, you can start Orthanc:: | |
215 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
216 $ docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro jodogne/orthanc-plugins |
54 | 217 |
218 | |
219 Debugging | |
220 --------- | |
221 | |
176 | 222 .. highlight:: text |
223 | |
54 | 224 For debugging purpose, you can start an interactive bash session as |
225 follows:: | |
226 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
227 $ docker run -i -t --rm --entrypoint=bash jodogne/orthanc |
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
228 $ docker run -i -t --rm --entrypoint=bash jodogne/orthanc-plugins |
175 | 229 |
176 | 230 For developers and power users, the images ``jodogne/orthanc-debug`` |
231 contain the Orthanc core compiled in debug mode (i.e. with runtime | |
232 assertions enabled, and including debugging symbols). A ``gdb`` | |
177 | 233 command-line session can be started as follows:: |
176 | 234 |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
358
diff
changeset
|
235 $ docker run -i -t --rm --entrypoint=bash --network=host --cap-add=SYS_PTRACE -p 4242:4242 -p 8042:8042 jodogne/orthanc-debug |
176 | 236 # gdb --args Orthanc /etc/orthanc/ --verbose |
175 | 237 |
184 | 238 Exceptions can be automatically caught by launching ``gdb`` as follows:: |
239 | |
240 # gdb --ex 'catch t' --ex r --ex bt --args ./Orthanc /etc/orthanc/ --verbose | |
241 | |
176 | 242 Note that: |
243 | |
244 * The plugins are not available in this image yet. | |
245 | |
246 * The Orthanc source code can be found in folder ``/root/orthanc``. | |
247 | |
248 * The build artifacts can be found in folder ``/root/orthanc/Build``. | |
249 | |
250 * This command launches the mainline version. To start a released version, | |
336 | 251 use e.g. ``jodogne/orthanc-debug:1.6.0``. |