Mercurial > hg > orthanc-book
annotate Sphinx/source/users/configuration.rst @ 888:8db34112a812
cont
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Thu, 27 Oct 2022 12:26:17 +0200 |
parents | f72b2dd172da |
children | 6474e299918b |
rev | line source |
---|---|
0 | 1 .. _configuration: |
2 | |
3 Configuration of Orthanc | |
4 ======================== | |
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 | 8 Configuring Orthanc simply consists in providing a configuration file. |
361 | 9 Orthanc has numerous configuration that are documented in the `default |
213 | 10 configuration file |
872 | 11 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.11.2/OrthancServer/Resources/Configuration.json>`_. This |
0 | 12 file is in the `JSON <https://en.wikipedia.org/wiki/JSON>`_ file |
361 | 13 format. You can generate this file file with the following call:: |
0 | 14 |
15 $ Orthanc --config=Configuration.json | |
16 | |
17 The default configuration file would: | |
18 | |
19 * Create a DICOM server with the DICOM AET (Application Entity Title) | |
20 ``ORTHANC`` that listens on the port 4242. | |
21 * Create a HTTP server for the REST API that listens on the port 8042. | |
22 * Store the Orthanc database in a folder called ``OrthancStorage``. | |
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 | 26 However, we recommend that you start from an empty configuration file |
27 and only specify the options for which you don't wan't to use | |
214 | 28 the default value. In example, a simple configuration file would be:: |
213 | 29 |
30 { | |
31 "Name": "My archive", | |
32 "HttpPort": 80, | |
33 "DicomAet": "ARCHIVE", | |
34 "DicomPort": 104 | |
35 } | |
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 | 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 | 45 Once your configuration file is ready, start Orthanc by giving it the path to the |
46 configuration file path as a command-line argument. If you use multiple configuration | |
47 files, you may provide the path to the folder containing all configuration files | |
48 (all ``.json`` files will be loaded):: | |
49 | |
50 $ Orthanc ./Configuration.json | |
51 $ Orthanc ./config/ | |
52 | |
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 | 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 |
a63e0ef60327
shutdown of windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
73 <https://bugs.orthanc-server.com/show_bug.cgi?id=48>`__. |
213 | 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 | 77 |
78 $ Orthanc ./Configuration.json --verbose | |
79 $ Orthanc ./Configuration.json --trace | |
80 | |
541 | 81 To learn more about the Orthanc logs, :ref:`check out the dedicated |
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 } |