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