It is recommended to install mercure on a Linux machine running Ubuntu Server 20.04 LTS 64bit (or newer). The installer for the Ubuntu operating system can be downloaded at https://ubuntu.com/download/server
mercure might run on other Linux distributions as well, but the installation script will not work without modification. When trying to install mercure on other Linux distributions, it might be best to focus on a Docker-based installation and derive a custom installation script from the script included in the repository.
mercure servers and the web-based user interface should never be placed on the internet! mercure has been designed for use in intranet environments that are secured against unauthorized access. It has not been hardened and tested for installation on the public internet. Also, DICOM transfers should never be made over the public internet (unless encrypted and secured transfer protocols are used, e.g. based on DICOMweb).
mercure can be installed in three different ways:
Using systemd as service runner
Using Docker as service runner
Using Nomad for orchestrating the services
Which installation type should you choose? It depends on the use case. For normal users, either a Docker-based or systemd-based installation is best suited. A systemd-based installation might have a small performance advantage, while a Docker-based installation will be easier to upgrade to newer mercure versions. If you are planning to actively develop and customize mercure, a systemd-based installation should be preferred.
With both systemd- and Docker-based installations, processing modules are executed sequentially, i.e. the requested processing module is launched inside a Docker container and the processor service waits until the processing has finished. With a Nomad-based installation, multiple processing modules can be executed in parallel. In this case, the processor service launches processing modules asynchronously and fetches results from the processing containers when the processing has finished. Moreover, the processor can distribute the processing jobs across multiple compute nodes, i.e. you can operate a processing cluster. This might be important if you are planning to integrate computationally demanding processing algorithms and if you are expecting a large volume of processing jobs. It is also relevant if you are planning to operate processing modules with different hardware requirements, because the Nomad-based solution allows defining resource requirements for jobs. However, these functions may not be needed in many situations. Nomad-based installations are more complex and intended for advanced users.
After deciding on the type of mercure installation, open a terminal shell of your Ubuntu installation for a user with sudo rights. Clone the mercure repository into the home folder of the user by typing the commands below. This will install the latest stable version, which is recommended. If you would like to install a specific version instead, replace “latest-stable” with the desired version tag. A list of all released versions can be found here.
git clone --branch latest-stable https://github.com/mercure-imaging/mercure.git
Call the installation script and put the installation type as argument (“systemd” or “docker” or “nomad”):
sudo ./install.sh systemd
The script will now perform all relevant installation steps, including installation of Docker and Python runtime environments. It will also create the user “mercure”, which will be used for running the mercure processes.
When installing mercure in Docker mode, the option “-b” can be used to enforce that the docker containers are rebuilt (instead of downloaded from Docker Hub). This might be helpful if you are interested in new features that have not been published as release yet. Moreover, the option “-d” selects the development version instead of the stable version.
By default, mercure is installed in the folder /opt/mercure. If necessary, the location can be changed after the installation (see note below), but this is not recommended. The installer will always use the default path.
Base installation folder
Application source code
Folders for buffering images
Database of the bookkeeper
If you need to change the installation location, set the environment variable MERCURE_CONFIG_FOLDER to the new location where the configuration files can be found. Then, change the paths of the data folders in the configuration file mercure.json. Finally, change the application startup scripts depending on your installation type. In the case of a systemd installation, this means adjusting mercure’s .service files found in the folder /etc/systemd/system.
The source code located in the /app folder is directly executed only for systemd-type installations. Docker and Nomad installations execute container images instead. By default, these images are downloaded from Docker Hub. If you want to modify the mercure source code, you need to rebuild the container images for the changes to go into effect. This can be done with the script build-docker.sh.
DICOM Reception over TLS Connection
Support for the DICOM TLS receiver mode is still experimental and should be used with care.
Due to an incompatibility in DICOM toolkit v3.6.4 and OpenSSL v1.1.1, the dcmtk and openssl versions supported by Ubuntu 20.04, only Ubuntu 22.04 mercure installs support TLS reception.
The following environment variables must be defined to run mercure in DICOM TLS receiver mode. This can be done, for example, by adding the values to the /etc/environment file. First, set MERCURE_TLS_ENABLED to 1. Next, specify the paths to your server TLS key, certificate, and CA certificate, as shown in the below sample configuration.
The following example shows how to create your own Certificate Authority (CA) to self-sign your own certificates. In production, you will likely use your organization’s certificate authority to sign the TLS receiver certificate, or create an intermediate CA from your organizational CA to sign CSR when generating certificates.
Here are some example steps to create a self-signed certificate authority and TLS key/certificate that can be utilized for use mercure in DICOM TLS receiver mode.
Step 1: Generate the CA key: openssl genrsa -out CA_key.pem 4096
Step 2: Create the CA certificate: openssl req -new -x509 -days 3650 -key CA_key.pem -out CA_certificate.pem
Step 3: Create a TLS private key: openssl genrsa -out SCP_private_key.pem 4096
Step 4: Create a CSR (Certificate Signing Request) with the TLS private key: openssl req -new -key private_key.pem -out receiver_csr.pem
Step 5: Sign the CSR with the CA private key and certificate to generate the TLS certificate: openssl x509 -req -days 3650 -in receiver_csr.pem -CA CA_certificate.pem -CAkey CA_key.pem -CAcreateserial -out certificate.pem
Step 6: Verify that the generated TLS certificate is valid against the CA certificate: openssl verify -CAfile CA_certificate.pem certificate.pem
When creating the CSR, ensure that the CSR common name is NOT the same as the CA common name. If so, the openssl certificate validation will fail and you will not be able to receive DICOM data over TLS.
Remember to add both your TLS receiver private key (private_key.pem), certificate file (certificate.pem), and CA certificate file (CA_certificate.pem) to the file system of your mercure installation and specify the above environment variables to enable TLS receiver mode.
If you have made it to here, then you have mastered the installation of mercure. You should now be able to access mercure’s user interface with a web browser by entering your server’s IP address and adding :8000 (e.g., 192.168.56.1:8000).
You can change the port used for the web interface from 8000 to another port by editing the file webgui.env in mercure’s configuration folder. Make sure to restart the webgui service afterwards. Also, if running Docker or Nomad (or testing mercure with Vagrant), make sure to modify the port mapping to the host system as well.