|
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
|
|
|
21 *Note for CentOS users:* The Docker environment might be difficult to
|
|
|
22 configure on your platform. Hints are available on the `Orthanc Users
|
|
|
23 discussion group
|
|
|
24 <https://groups.google.com/d/msg/orthanc-users/w-uPAknnRQc/-XhzBGSCAwAJ>`__.
|
|
|
25
|
|
|
26
|
|
|
27 Running the Orthanc core
|
|
|
28 ------------------------
|
|
|
29
|
|
|
30 The following command will start the core of Orthanc, with all the
|
|
|
31 plugins disabled::
|
|
|
32
|
|
|
33 $ sudo docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc
|
|
|
34
|
|
|
35 Once Orthanc is running, use Mozilla Firefox at URL
|
|
|
36 http://localhost:8042/ to interact with Orthanc. The default username
|
|
|
37 is ``orthanc`` and its password is ``orthanc``.
|
|
|
38
|
|
|
39 The command above starts the mainline version of Orthanc, whose
|
|
69
|
40 development is in continuous progress. Do not forget to regularly
|
|
|
41 update the Docker image to benefit from the latest features::
|
|
|
42
|
|
|
43 $ sudo docker pull jodogne/orthanc
|
|
|
44
|
|
|
45 If more stability is required, you can select the official release of
|
|
|
46 Orthanc to be run::
|
|
54
|
47
|
|
178
|
48 $ sudo docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc:1.5.0
|
|
54
|
49
|
|
|
50 Passing additional command-line options (e.g. to make Orthanc verbose)
|
|
|
51 can be done as follows (note the ``/etc/orthanc`` option that is
|
|
|
52 required for Orthanc to find its configuration files)::
|
|
|
53
|
|
|
54 $ sudo docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc /etc/orthanc --verbose
|
|
|
55
|
|
|
56
|
|
|
57 Usage, with plugins enabled
|
|
|
58 ---------------------------
|
|
|
59
|
|
|
60 The following command will run the mainline version of the Orthanc
|
|
|
61 core, together with its :ref:`Web viewer <webviewer>`, its
|
|
|
62 :ref:`PostgreSQL support <postgresql>`, its :ref:`DICOMweb
|
|
|
63 implementation <dicomweb>`, and its :ref:`whole-slide imaging viewer
|
|
|
64 <wsi>`::
|
|
|
65
|
|
|
66 $ sudo docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-plugins
|
|
|
67
|
|
|
68
|
|
|
69 Fine-tuning the configuration
|
|
|
70 -----------------------------
|
|
|
71
|
|
|
72 For security reasons, you should at least protect your instance of
|
|
|
73 Orthanc by changing this default user, in the ``RegisteredUsers``
|
|
|
74 :ref:`configuration option <configuration>`. You will also probably
|
|
|
75 need to fine-tune other parameters, notably the list of the DICOM
|
|
|
76 modalities Orthanc knows about.
|
|
|
77
|
|
|
78 You can generate a custom configuration file for Orthanc as follows::
|
|
|
79
|
|
|
80 $ sudo docker run --rm --entrypoint=cat jodogne/orthanc /etc/orthanc/orthanc.json > /tmp/orthanc.json
|
|
|
81
|
|
|
82 Then, edit the just-generated file ``/tmp/orthanc.json`` and restart
|
|
|
83 Orthanc with your updated configuration::
|
|
|
84
|
|
|
85 $ sudo docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro jodogne/orthanc
|
|
|
86
|
|
|
87
|
|
|
88 Making the Orthanc database persistent
|
|
|
89 --------------------------------------
|
|
|
90
|
|
|
91 The filesystem of Docker containers is volatile (its content is
|
|
|
92 deleted once the container stops). You can make the Orthanc database
|
|
|
93 persistent by mapping the ``/var/lib/orthanc/db`` folder of the
|
|
|
94 container to some path in the filesystem of your Linux host, e.g.::
|
|
|
95
|
|
|
96 $ mkdir /tmp/orthanc-db
|
|
178
|
97 $ sudo docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc-db/:/var/lib/orthanc/db/ jodogne/orthanc:1.5.0
|
|
54
|
98
|
|
|
99
|
|
|
100 Whole-slide imaging support
|
|
|
101 ---------------------------
|
|
|
102
|
|
|
103 The ``orthanc-plugins`` image includes support for :ref:`microscopic
|
|
|
104 whole-slide imaging (WSI) <wsi>`. For instance, the following command
|
|
|
105 will start the WSI viewer plugin transparently together with Orthanc::
|
|
|
106
|
|
|
107 $ sudo docker run -p 4242:4242 -p 8042:8042 --rm --name orthanc-wsi jodogne/orthanc-plugins
|
|
|
108
|
|
|
109 Note that we gave the name ``orthanc-wsi`` to this new Docker
|
|
|
110 container. Then, the Dicomizer command-line tool can be invoked as
|
|
|
111 follows::
|
|
|
112
|
|
|
113 $ sudo 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
|
|
|
114
|
|
|
115 This command needs a few explanations:
|
|
|
116
|
|
|
117 * ``--link=orthanc-wsi:orthanc`` links the container running the
|
|
|
118 Dicomizer, to the Docker container running Orthanc that we started
|
|
|
119 just before.
|
|
|
120 * ``--entrypoint=OrthancWSIDicomizer`` specifies that the Dicomizer
|
|
|
121 must be run instead of the Orthanc server.
|
|
|
122 * ``-v /tmp/Source.tif:/tmp/Source.tif:ro`` maps the source image
|
|
|
123 ``/tmp/Source.tif`` on the host computer into the Orthanc container
|
|
|
124 as read-only file ``/tmp/Source.tif``.
|
|
|
125 * ``--orthanc=http://orthanc:8042/`` instructs the Dicomizer to push
|
|
|
126 images through the ``--link`` created above.
|
|
|
127 * ``--username=orthanc --password=orthanc`` correspond to the default
|
|
|
128 credentials of the ``orthanc-plugins`` image.
|
|
|
129
|
|
|
130 Obviously, you are free to add all the options you wish (check out the
|
|
|
131 ``--help`` flag to list these options). In particular, the
|
|
|
132 ``--dataset`` option allows to specify DICOM tags, in the JSON file
|
|
|
133 format, so as to include them in the resulting DICOM series (the
|
|
|
134 option ``--sample-dataset`` prints a sample JSON file that has the
|
|
|
135 expected format).
|
|
|
136
|
|
|
137 If you have a source image that is not a hierarchical TIFF, you must
|
|
|
138 instruct the Dicomizer to use `OpenSlide <http://openslide.org/>`__ to
|
|
|
139 decode it by adding the ``--openslide`` option::
|
|
|
140
|
|
|
141 $ sudo 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
|
|
|
142
|
|
|
143
|
|
|
144 PostgreSQL and Orthanc inside Docker
|
|
|
145 ------------------------------------
|
|
|
146
|
|
|
147 It is possible to run both Orthanc and PostgreSQL inside Docker. First, start the official PostgreSQL container::
|
|
|
148
|
|
|
149 $ sudo docker run --name some-postgres -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=pgpassword --rm postgres
|
|
|
150
|
|
|
151 Open another shell, and create a database to host the Orthanc database::
|
|
|
152
|
|
|
153 $ sudo 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'
|
|
|
154
|
|
|
155 You will have to type the password (cf. the environment variable
|
|
|
156 ``POSTGRES_PASSWORD`` above that it set to ``pgpassword``). Then,
|
|
|
157 retrieve the IP and the port of the PostgreSQL container, together
|
|
|
158 with the default Orthanc configuration file::
|
|
|
159
|
|
|
160 $ sudo docker inspect --format '{{ .NetworkSettings.IPAddress }}' some-postgres
|
|
|
161 $ sudo docker inspect --format '{{ .NetworkSettings.Ports }}' some-postgres
|
|
|
162 $ sudo docker run --rm --entrypoint=cat jodogne/orthanc-plugins /etc/orthanc/orthanc.json > /tmp/orthanc.json
|
|
|
163
|
|
|
164 .. highlight:: json
|
|
|
165
|
|
|
166 Add the following section to ``/tmp/orthanc.json`` (adapting the
|
|
|
167 values Host and Port to what docker inspect said above)::
|
|
|
168
|
|
|
169 "PostgreSQL" : {
|
|
|
170 "EnableIndex" : true,
|
|
|
171 "EnableStorage" : true,
|
|
|
172 "Host" : "172.17.0.38",
|
|
|
173 "Port" : 5432,
|
|
|
174 "Database" : "orthanc",
|
|
|
175 "Username" : "postgres",
|
|
|
176 "Password" : "pgpassword"
|
|
|
177 }
|
|
|
178
|
|
|
179 .. highlight:: bash
|
|
|
180
|
|
|
181 Finally, you can start Orthanc::
|
|
|
182
|
|
|
183 $ sudo docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro jodogne/orthanc-plugins
|
|
|
184
|
|
|
185
|
|
|
186 Debugging
|
|
|
187 ---------
|
|
|
188
|
|
176
|
189 .. highlight:: text
|
|
|
190
|
|
54
|
191 For debugging purpose, you can start an interactive bash session as
|
|
|
192 follows::
|
|
|
193
|
|
|
194 $ sudo docker run -i -t --rm --entrypoint=bash jodogne/orthanc
|
|
|
195 $ sudo docker run -i -t --rm --entrypoint=bash jodogne/orthanc-plugins
|
|
175
|
196
|
|
176
|
197 For developers and power users, the images ``jodogne/orthanc-debug``
|
|
|
198 contain the Orthanc core compiled in debug mode (i.e. with runtime
|
|
|
199 assertions enabled, and including debugging symbols). A ``gdb``
|
|
177
|
200 command-line session can be started as follows::
|
|
176
|
201
|
|
177
|
202 $ sudo docker run -i -t --rm --entrypoint=bash --network=host --cap-add=SYS_PTRACE -p 4242:4242 -p 8042:8042 jodogne/orthanc-debug
|
|
176
|
203 # gdb --args Orthanc /etc/orthanc/ --verbose
|
|
175
|
204
|
|
176
|
205 Note that:
|
|
|
206
|
|
|
207 * The plugins are not available in this image yet.
|
|
|
208
|
|
|
209 * The Orthanc source code can be found in folder ``/root/orthanc``.
|
|
|
210
|
|
|
211 * The build artifacts can be found in folder ``/root/orthanc/Build``.
|
|
|
212
|
|
|
213 * This command launches the mainline version. To start a released version,
|
|
178
|
214 use e.g. ``jodogne/orthanc-debug:1.5.0``.
|
