Mercurial > hg > orthanc-book

annotate Sphinx/source/users/configuration.rst @ 1000:2e103fb1fa11

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Orthanc 1.12.2
author Alain Mazy <am@osimis.io>
date Tue, 19 Dec 2023 17:54:15 +0100
parents 1316bc62b5d5
children 17bf6fafb884
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _configuration:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3 Configuration of Orthanc
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 ========================
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5
664
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
6 .. highlight:: bash
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
7
213
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
8 Configuring Orthanc simply consists in providing a configuration file.
361
84e3a2612c36 links to hg
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 336
diff changeset
9 Orthanc has numerous configuration that are documented in the `default
213
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
10 configuration file
1000
2e103fb1fa11 Orthanc 1.12.2
Alain Mazy <am@osimis.io>
parents: 991
diff changeset
11 <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.2/OrthancServer/Resources/Configuration.json>`_. This
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12 file is in the `JSON <https://en.wikipedia.org/wiki/JSON>`_ file
361
84e3a2612c36 links to hg
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 336
diff changeset
13 format. You can generate this file file with the following call::
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15 $ Orthanc --config=Configuration.json
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
16
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17 The default configuration file would:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
18
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19 * Create a DICOM server with the DICOM AET (Application Entity Title)
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
20 ``ORTHANC`` that listens on the port 4242.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
21 * Create a HTTP server for the REST API that listens on the port 8042.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
22 * Store the Orthanc database in a folder called ``OrthancStorage``.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
23
664
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
24 .. highlight:: json
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
25
213
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
26 However, we recommend that you start from an empty configuration file
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
27 and only specify the options for which you don't wan't to use
214
amazy
parents: 213
diff changeset
28 the default value. In example, a simple configuration file would be::
213
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
29
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
30 {
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
31 "Name": "My archive",
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
32 "HttpPort": 80,
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
33 "DicomAet": "ARCHIVE",
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
34 "DicomPort": 104
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
35 }
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
36
653
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
37 It's also a very good practice to split your configuration files per
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
38 topic. In example, have a ``dicom.json`` for everything that is
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
39 related to DICOM, a ``http.json`` for all HTTP related configurations,
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
40 one file per plugin. This is how the configuration files are provided
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
41 with the Windows Installer.
213
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
42
664
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
43 .. highlight:: bash
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
44
213
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
45 Once your configuration file is ready, start Orthanc by giving it the path to the
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
46 configuration file path as a command-line argument. If you use multiple configuration
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
47 files, you may provide the path to the folder containing all configuration files
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
48 (all ``.json`` files will be loaded)::
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
49
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
50 $ Orthanc ./Configuration.json
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
51 $ Orthanc ./config/
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
52
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
53
653
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
54 **Remark 1:** When specifying paths under Microsoft Windows,
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
55 backslashes (i.e. ``\``) should be either escaped by doubling them (as
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
56 in ``\\``), or replaced by forward slashes (as in ``/``).
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
57
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
58 **Remark 2:** When installing Orthanc using the Windows installer by
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
59 Osimis, you won't be able to edit your files unless you start your
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
60 editor with ``Run as administrator``. We recommend to edit your
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
61 configuration file with an editor such as `Notepad++
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
62 <https://notepad-plus-plus.org/>`_. It shall warn you that this file
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
63 can be edited only by an admin, and will suggest you to restart
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
64 Notepad++ as an admin such that you'll be able to save it.
73
c742c8f9ffa3 encodings
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 72
diff changeset
65
653
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
66 **Remark 3:** The Windows installers by Osimis provide a `Windows
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
67 service <https://en.wikipedia.org/wiki/Windows_service>`__ that
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
68 automatically starts Orthanc during the startup of Microsoft
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
69 Windows. You can control the parameters of the service by typing
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
70 ``services.msc`` at a command-line prompt. The Windows service of
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
71 Orthanc will do its best to cleanly stop Orthanc at the shutdown of
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
72 Windows, but `there are some caveats
991
1316bc62b5d5 migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 963
diff changeset
73 <https://orthanc.uclouvain.be/bugs/show_bug.cgi?id=48>`__.
213
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
74
653
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
75 **Remark 4:** To obtain more diagnostic, you can use the ``--verbose``
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
76 or the ``--trace`` options::
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
77
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
78 $ Orthanc ./Configuration.json --verbose
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
79 $ Orthanc ./Configuration.json --trace
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
80
541
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 528
diff changeset
81 To learn more about the Orthanc logs, :ref:`check out the dedicated
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 528
diff changeset
82 page <log>`.
664
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
83
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
84
673
767c2550fa00 environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 664
diff changeset
85 .. _orthanc-environment-variables:
767c2550fa00 environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 664
diff changeset
86
664
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
87 Environment variables
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
88 ---------------------
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
89
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
90 .. highlight:: json
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
91
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
92 Starting with Orthanc 1.5.0, the configuration file can include the
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
93 value of environment variables. Consider the following configuration::
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
94
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
95 {
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
96 "Name" : "${ORTHANC_NAME}"
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
97 }
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
98
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
99
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
100 .. highlight:: bash
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
101
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
102 In this case, once Orthanc starts, the configuration option ``Name``
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
103 will be read from the value of the environment variable
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
104 ``ORTHANC_NAME``. For instance::
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
105
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
106 $ ORTHANC_NAME=Hello ./Orthanc Configuration.json
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
107 $ curl http://localhost:8042/system
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
108 {
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
109 "Name" : "Hello",
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
110 [...]
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
111 }
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
112
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
113
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
114 .. highlight:: json
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
115
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
116 It is also possible to set a default value if the environment variable
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
117 is not set. Here is the syntax in the configuration file::
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
118
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
119 {
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
120 "Name" : "${ORTHANC_NAME:-DefaultName}"
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
121 }
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
122
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
123
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
124 .. highlight:: bash
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
125
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
126 If the environment variable ``ORTHANC_NAME`` is not set, here is the
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
127 result::
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
128
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
129 $ ./Orthanc Configuration2.json
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
130 $ curl http://localhost:8042/system
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
131 {
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
132 "Name" : "DefaultName",
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
133 [...]
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
134 }