Mercurial > hg > orthanc-book

comparison Sphinx/source/users/docker.rst @ 54:bd0fbf1f0143

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docker documentation
author Sebastien Jodogne <s.jodogne@gmail.com>
date Tue, 08 Nov 2016 14:51:11 +0100
parents
children 03d35f985f26
comparison
equal deleted inserted replaced
53:22b6ed6c9d5c 54:bd0fbf1f0143
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