Configuration of Orthanc¶

Configuring Orthanc simply consists in providing a configuration file. Orthanc has numerous configuration that are documented in the default configuration file. This file is in the JSON file format. You can generate this file file with the following call:

$ Orthanc --config=Configuration.json

The default configuration file would:

Create a DICOM server with the DICOM AET (Application Entity Title) ORTHANC that listens on the port 4242.
Create a HTTP server for the REST API that listens on the port 8042.
Store the Orthanc database in a folder called OrthancStorage.

However, we recommend that you start from an empty configuration file and only specify the options for which you don’t wan’t to use the default value. In example, a simple configuration file would be:

{
    "Name": "My archive",
    "HttpPort": 80,
    "DicomAet": "ARCHIVE",
    "DicomPort": 104
}

It’s also a very good practice to split your configuration files per topic. In example, have a dicom.json for everything that is related to DICOM, a http.json for all HTTP related configurations, one file per plugin. This is how the configuration files are provided with the Windows Installer.

Once your configuration file is ready, start Orthanc by giving it the path to the configuration file path as a command-line argument. If you use multiple configuration files, you may provide the path to the folder containing all configuration files (all .json files will be loaded):

$ Orthanc ./Configuration.json
$ Orthanc ./config/

Remark 1: When specifying paths under Microsoft Windows, backslashes (i.e. \) should be either escaped by doubling them (as in \\), or replaced by forward slashes (as in /).

Remark 2: When installing Orthanc using the official Windows installers, you won’t be able to edit your files unless you start your editor with Run as administrator. We recommend to edit your configuration file with an editor such as Notepad++. It shall warn you that this file can be edited only by an admin, and will suggest you to restart Notepad++ as an admin such that you’ll be able to save it.

Remark 3: The official Windows installers include a Windows service that automatically starts Orthanc during the startup of Microsoft Windows. You can control the parameters of the service by typing services.msc at a command-line prompt. The Windows service of Orthanc will do its best to cleanly stop Orthanc at the shutdown of Windows, but there are some caveats.

Remark 4: To obtain more diagnostic, you can use the --verbose or the --trace options:

$ Orthanc ./Configuration.json --verbose
$ Orthanc ./Configuration.json --trace

To learn more about the Orthanc logs, check out the dedicated page.

Environment variables¶

Starting with Orthanc 1.5.0, the configuration file can include the value of environment variables. Consider the following configuration:

{
  "Name" : "${ORTHANC_NAME}"
}

In this case, once Orthanc starts, the configuration option Name will be read from the value of the environment variable ORTHANC_NAME. For instance:

$ ORTHANC_NAME=Hello ./Orthanc Configuration.json
$ curl http://localhost:8042/system
{
  "Name" : "Hello",
  [...]
}

It is also possible to set a default value if the environment variable is not set. Here is the syntax in the configuration file:

{
  "Name" : "${ORTHANC_NAME:-DefaultName}"
}

If the environment variable ORTHANC_NAME is not set, here is the result:

$ ./Orthanc Configuration2.json
$ curl http://localhost:8042/system
{
  "Name" : "DefaultName",
  [...]
}