Advanced Topics

Configuration files

mercure stores the configuration in multiple files in the subfolder /opt/mercure/config. If you want to backup the configuration or install mercure on another machine, you need to copy all files inside this folder. During installation of mercure, these files are generated from template files contained in the folder /opt/mercure/app/configuration.




Contains IP, port, and DB password for the bookkeeper service


Configured rules, targets, modules, and other mercure settings


List of configured mercure services (must be modified for scaling services)


User account information for the web interface


Contains IP, port, and secret key for the web interface

Additional settings

Advanced settings can be reviewed and adjusted on the Configuration page of the web interface. To change the settings, click the “Edit Settings” button at the bottom of the page. Once saved, the different service modules will automatically load the updated configuration.


Make sure to preserve correct JSON formatting of the settings. The web interface will automatically check the syntax before saving the file.

Alternatively to using the web interface, the changes can also be made by directly editing the file mercure.json with a Linux text editor, e.g. nano.


When editing the configuration file directly, it is required to shutdown all mercure services prior to making any changes (via the web interface or systemctl command).

The following settings can be customized (default values can be found in default_mercure.json):




Optional name of the mercure server (useful for multiple servers)


Port for receiving DICOMs (default: 11112). Must be >1024 for non-root service user.


Enable reception of compressed DICOMs. Use with care (see below). Requires that all processing modules can handle compressed images.


Buffer location for received DICOM files


Buffer location for collecting series belonging to one study


Buffer location for series to be dispatched


Storage location for completed series until retention period has passed


Storage location for files that could not be parsed or dispatched


Storage location for discarded series until retention period has passed


Buffer location for series to be processed


IP and port of the bookkeeper instance


IP address of the graphite server. Leave empty if none


Port of the graphite server


Interval how often the router checks for arrived images (sec)


Time after arrival of last slice when series is considered complete (sec)


Time after arrival of last series when study is considered complete (sec)


Time after which studies are considered complete even if series are missing (sec)


Interval how often the dispatcher checks for series to be sent (sec)


Delay before retrying to dispatch series after failure (sec)


Maximum number of retries when dispatching


Interval how often the cleaner checks for files to be deleted (sec)


Duration how long files will be kept before deletion (sec)


Percentage of disk usage that triggers emergency cleaning


Start of the off-peak work hours (24h format)


End of the off-peak work hours (24h format)


Configured targets - should be edited via web interface


Configured rules - should be edited via web interface


Configured modules - should be edited via web interface


By default, the mercure DICOM receiver requests incoming DICOM images in uncompressed format. Thus, compressed images need to be decompressed by the sender prior to the transfer (e.g., if sending cases from a PACS that stores images in compressed form). This avoids potential incompatibilities between different implementations of the compression algorithms and ensures best compatibility. If using mercure solely for routing purpose, it can be more efficient to accept images also in compressed form. This can be enabled by setting accept_compressed_images to “True”. However, this setting requires that all processing modules that are installed on the mercure server need to be able to handle compressed images (this might not be the case for many modules, including the demo modules). Also, if accepting compressed images, it can happen that the images will still be decompressed during dispatching if the target DICOM node indicates preference for uncompressed images.

Scaling services

By default, mercure uses only a single instance of each service module (i.e., in the case of the dispatcher, only one series per time is sent outwards). This provides sufficient performance for most applications. However, for demanding applications with very high volume of incoming DICOM series, it can be necessary run multiple instances of the modules (router, processor, dispatcher). All mercure modules have been written to allow for parallel execution, so that additional instances can be started.

The exact procedure for scaling up services depends on the type of mercure installation (systemd / Docker / Nomad). The instructions below describe how services can be duplicated when using systemd (which is preferred for high-performance installations).

For systemd installations, the file services.json in the folder /opt/mercure/config needs to be modified. Here, the section of each module that should be scaled needs to be duplicated. For example, for scaling the dispatcher, the “dispatcher” section needs to be duplicated and a unique name needs to be selected for the copy (for the section name and inner keys “name” and “systemd_service”, as shown below):

    "dispatcher": {
        "name": "Dispatcher",
        "systemd_service": "mercure_dispatcher.service",
        "docker_service": "mercure_dispatcher_1"
    "dispatcher2": {
        "name": "Dispatcher2",
        "systemd_service": "mercure_dispatcher2.service",
        "docker_service": "mercure_dispatcher_2"


It is not necessary to scale the receiver module, as the receiver automatically launches a separate process for every DICOM connection.

Afterwards, the .service files of the scaled service modules need to be duplicated in the folder /etc/systemd/system. For example, if duplicating the dispatcher module as shown above, copy the existing file mercure_dispatcher.service and name it mercure_dispatcher2.service (or whatever has been listed in the file services.json). Enable and start the duplicated service by calling (from an account with sudo rights):

sudo systemctl enable mercure_dispatcher2.service
sudo systemctl start mercure_dispatcher2.service

As last step, it is necessary to authorize the mercure system user to control the duplicated services. This is done by editing the file /etc/sudoers.d/mercure (using a user account with sudo permission) and adding a line for each duplicated service (according to the name specified above). When copying an existing line from the file, make sure to change every occurrence of the service name in the line.