MRIdb Reference Guide

Overview

The MRIdb system is composed of two components: an pre-configured instance of the open-source DCM4CHEE DICOM server and a bespoke web application, henceforth referred to as MRIdb, which provides a user-friendly interface for searching and viewing imported images. Both are written in Java, though MRIdb depends on some native tools and libraries in order to perform image format conversion.

MRIdb was developed at Imperial College London by Mark Woodbridge (Bioinformatics Support Service). The project was commissioned by Declan O’Regan (Robert Steiner MR Unit) and technical oversight was provided by Gianlorenzo Fagiolo (MRC Clinical Sciences Centre).

Access to the source code and other information is available at the MRIdb home page.

Virtual machine

A virtual appliance in OVF format (generated using VirtualBox 4.3.6) is available from the MRdb home page. It uses ports 8080 (dcm4chee-web), 11112 (dcm4chee-dicom), 2222 (ssh) and 9000 (mridb). The root (operating system) password is “password”. No further configuration is necessary unless you require LDAP authentication.

Please note the the VM typically lags behind MRIdb releases. Please consider building your own VM using the installation script below in order to trial the latest version.

Getting started with the MRIdb virtual machine:

1. Install VirtualBox
2. Download and import the MRIdb VM
3. Download and send some images using a DICOM storage SCU e.g. dcm4che-2.0.28/bin/dcmsnd DCM4CHEE@localhost:11112 sample1
4. Access the web interface at http://localhost:9000 as user “mri1”, password “mri1”

The mri1 user is an administrator and can create other users.

Important: for security purposes the passwords of the mri1 (MRIdb) and root (OS) users should be changed and any keys in /root/.ssh/authorized_keys removed before using the VM with real images

A standalone (non-virtualised) MRIdb setup is recommended for production use (see 'Installation' below).

Components

MRIdb has been developed for Enterprise Linux (CentOS) 6. A full list of runtime dependencies is listed in the ‘Installation’ section below.

The infrastructure components required and provided by MRIdb are:

• A Linux server (extensively tested using CentOS 6, lightly tested using CentOS 7)
• An LDAP server (optional, tested using Active Directory)
• A storage system (e.g. a NAS mounted over NFS)
• A PostgreSQL server (tested using 8.4)
• JBoss/DCM4CHEE (tested using 2.17.3)

Architecture

MRIdb Architecture (PowerPoint)

Note that dcm4chee interfaces directly with the storage system, and therefore must be stopped before maintenance of the storage system in order to prevent DICOM imports being accepted during this time. Note also that MRIdb depends on dcm4chee being operational.

Configuration

(See ‘Installation’ below for further details)

OS

• Ports 80, 8080 and 11112 opened (iptables)

PostgreSQL

• /etc/sysconfig/pgsql/postgresql (EL6), /etc/systemd/system/postgresql.service (EL7)
  • PGDATA - directory used for table storage

DCM4CHEE

• /etc/sysconfig/dcm4chee
  • JBoss user name and installation directory
  • Admin credentials (JBOSS_ADMIN_USER and JBOSS_ADMIN_PASSWORD)
• $DCM4CHEE_HOME/server/default/deploy/pacs-postgres-ds.xml
  • PostgreSQL connection details
• /opt/dcm4chee/server/default/archive symlink
  • DICOM storage location

MRIdb

• /opt/mridb/conf/application.conf
  • DCM4CHEE and database host settings
• /opt/mridb/conf/application-site.conf
  • LDAP host setting, exception reporting email address
• /opt/mridb/conf/log4j-prod.properties
  • Logging properties

Operation

Firstly ssh into the mridb server, then use the relevant command below.

DCM4CHEE

• sudo service dcm4chee {start|stop|restart}
• To kill forcefully (may be necessary if an OutOfMemoryError occurs when using the dcm4chee web interface):
  • sudo pkill -9 -f dcm4chee

MRIdb

• Normal operation:
  • sudo service mridb {start|stop|restart}
• To kill forcefully:
  • sudo pkill -f play.server.Server ; rm /var/lock/subsys/mridb

Logs

DCM4CHEE

• $DCM4CHEE_HOME/server/default/log/server.log

MRIdb

• /opt/mridb/logs/mridb.log
• Any exceptions that occur during operation are emailed to the address (if any) configured in /opt/mridb/conf/application-site.conf

System administration

The following actions should be performed by the local computing service:

• Backup
  • VM (all application code and configuration)
  • Database (PostgreSQL files)
  • Images (storage system)
• Operating system updates
• Monitoring of disk usage, NFS status, and the MRIdb, JBoss and PostgreSQL OS processes using Nagios or equivalent
• Stopping and restarting the application e.g. during file system maintenance

It should not be necessary to inspect the database, but this can be achieved by running PGUSER=postgres psql pacsdb

Application administration

MRIdb users with the ‘Administrator’ role are able to perform the following tasks using the normal web interface:

• User role management (i.e. creating other Administrators)
• Updates to the FAQ on the Help page
• Project renaming and removal of unused projects
• Viewing of the Audit log’ of user actions (currently login, download, export and patient-project assignments)

There are three roles in the system: Administrator, Researcher and Visitor. The latter can only view anonymised patient records. Note that user records are created the first time a user logs in (meaning that a user who has never logged in cannot be made an Administrator).

Security

If LDAP is configured then any user who is able to authenticate with the LDAP server is able to login to MRIdb.

Care should be taken when assigning the Administrator role but it does not provide the relevant user with access to more patient information or images than the Researcher role.

Operating system updates should be applied regularly. The VM is isolated but has full access to the unanonymised DICOM archive.

MRIdb only permits download of anonymised data, and allows passwords to be set for clipboard export archives.

The following firewall rules should be applied:


• Port 80 (web) and port 8080 (WADO) should be open to all hosts
• Port 11112 should be open to scanners only

Port 11112 is sensitive as it allows unrestricted DICOM query access to the entire archive. Port 8080 is required to be open for WADO (particularly Weasis) functionality. Authenticated administrative services (JBOSS JMX Console and the DCM4CHEE Archive Administration interface) are also serviced using this port so it is very important that the JBOSS admin credentials are changed from their default values (see ‘Configuration files’ above).

Installation

An install script (EL6, EL7) is available, which can be run on a clean installation of CentOS. It automatically downloads and install MRIdb and its prerequisites. Reboot the system to finalise installation. MRIdb will be started automatically.

Important: the standalone installation uses the standard ports for HTTP and SSH i.e. the MRIdb interface is available on port 80 (rather than 9000) and ssh is on port 22 (rather than 2222). The DICOM and WADO ports remain unchanged (11112 and 8080 respectively).

MRIdb binaries and the required dependencies package are also available from the MRIdb web page, along with a pre-configured VM.

Upgrading

MRIdb

This should be performed with caution:

1. Retrieve the latest .tar.bz2 file from https://github.com/mwoodbri/MRIdb/releases/latest
2. service mridb stop
3. tar xf mridb-xxx.tar.bz2 -C /opt
4. service mridb start

Note that this will interrupt any batch exports or audits that are in progress.

Note also that in the default configuration the MRIdb init script is provided by the binary distribution package and symlinked to /etc/init.d. It will therefore be overwritten during an upgrade unless unlinked (which is not recommended, as any updates will have to applied manually).

DCM4CHEE

It is only recommended to upgrade between point releases (i.e. where there are no schema changes).

Stop mridb and dcm4chee, follow the DCM4CHEE upgrade documentation, and then restart dcm4chee and mridb.

Data migration

Manual

/opt/dcm4che-2.0.28/bin/dcmsnd DCM4CHEE@localhost:11112 <folder>

Import of individual files (rather than folders) is not recommended due to a bug in recent versions of dcm4che.

Automatic

There is a resumable batch import script at /opt/mridb/bin/import.sh. It is run using cron (@reboot). It requires a file, import.txt, containing a list of folders to import. This file is updated in place as folders are imported. It can be generated using this command (or similar):

for i in /GRIDb/01/1/* /GRIDb/01/2/* /GRIDb/01/3/* /GRIDb/02/4/* /GRIDb/02/5/* /GRIDb/02/6/* ; do echo $i >>~/import/import.txt ; done

The script uses dcm4che’s dcmsnd command. The output from this command is directed to import.stout, with errors sent to import.stderr. A log of successfully imported folders is stored in import.log.

Dependencies

The contents of the mridb-deps.tar package are:

• dcm4che-2.0.28-bin.zip source
• dcm4chee-2.17.3-psql.zip source
• dcm4chee-attribute-filter.patch
• dcm4chee_init_redhat.patch
• dcmtk-3.6.0-linux-i686-static.tar.bz2 source
• ISD_dicom_tool.zip (07/2012)
• jai_imageio-1_1-lib-linux-amd64.tar.gz source
• jboss-4.2.3.GA-jdk6.zip source
• lx64.zip (6/2013) source
• play-1.2.x.zip (patched)
• weasis-pacs-connector.war (4.0.0) source
• weasis.war (1.2.8) source
• xmedcon-0.13.0.tar.gz source