Mercurial > hg > orthanc-book

annotate Sphinx/source/users/configuration.rst @ 1027:60b0b7ea409b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
migration to orthancteam
author Sebastien Jodogne <s.jodogne@gmail.com>
date Fri, 02 Feb 2024 14:16:55 +0100
parents a3436ae3709c
children d2be251975d1
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
1021
a3436ae3709c Orthanc 1.12.3
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1004
diff changeset
11 <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.3/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
1004
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
58 **Remark 2:** When installing Orthanc using the `official Windows
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
59 installers <https://www.orthanc-server.com/download-windows.php>`__,
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
60 you won't be able to edit your files unless you start your editor with
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
61 ``Run as administrator``. We recommend to edit your configuration file
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
62 with an editor such as `Notepad++ <https://notepad-plus-plus.org/>`_.
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
63 It shall warn you that this file can be edited only by an admin, and
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
64 will suggest you to restart Notepad++ as an admin such that you'll be
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
65 able to save it.
73
c742c8f9ffa3 encodings
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 72
diff changeset
66
1004
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
67 **Remark 3:** The official Windows installers include a `Windows
653
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
68 service <https://en.wikipedia.org/wiki/Windows_service>`__ that
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
69 automatically starts Orthanc during the startup of Microsoft
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
70 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
71 ``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
72 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
73 Windows, but `there are some caveats
991
1316bc62b5d5 migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 963
diff changeset
74 <https://orthanc.uclouvain.be/bugs/show_bug.cgi?id=48>`__.
213
f40f7d15e6bb updated configuration file section
amazy
parents: 196
diff changeset
75
653
a63e0ef60327 shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
76 **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
77 or the ``--trace`` options::
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
78
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
79 $ Orthanc ./Configuration.json --verbose
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
80 $ Orthanc ./Configuration.json --trace
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
81
541
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 528
diff changeset
82 To learn more about the Orthanc logs, :ref:`check out the dedicated
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 528
diff changeset
83 page <log>`.
664
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
84
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
85
673
767c2550fa00 environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 664
diff changeset
86 .. _orthanc-environment-variables:
767c2550fa00 environment variable in docker compose
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 664
diff changeset
87
664
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
88 Environment variables
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
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
91 .. highlight:: json
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
92
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
93 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
94 value of environment variables. Consider the following configuration::
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 {
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
97 "Name" : "${ORTHANC_NAME}"
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
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
101 .. highlight:: bash
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
102
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
103 In this case, once Orthanc starts, the configuration option ``Name``
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
104 will be read from the value of the environment variable
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
105 ``ORTHANC_NAME``. For instance::
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
106
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
107 $ ORTHANC_NAME=Hello ./Orthanc Configuration.json
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
108 $ curl http://localhost:8042/system
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
109 {
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
110 "Name" : "Hello",
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
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
115 .. highlight:: json
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
116
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
117 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
118 is not set. Here is the syntax in the configuration file::
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 {
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
121 "Name" : "${ORTHANC_NAME:-DefaultName}"
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
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
125 .. highlight:: bash
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
126
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
127 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
128 result::
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
129
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
130 $ ./Orthanc Configuration2.json
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
131 $ curl http://localhost:8042/system
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
132 {
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
133 "Name" : "DefaultName",
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
134 [...]
7fbe9147423f environment variables
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 653
diff changeset
135 }