Installation prerequisites¶

Install python 2.7

• Linux - likely to be installed already
• Windows - https://www.python.org/download/releases

Install setuptools and pip

Install OpenREM¶

• pip install openrem (Needs internet connection)

Configure OpenREM¶

Locate install location

• Linux: /usr/lib/python2.7/dist-packages/openrem/ or /usr/lib/python2.7/site-packages/openrem/
• Windows: C:\Python27\Lib\site-packages\openrem\

There are two files that need renaming: (changed for 0.4.0)

• openrem/local_settings.py.example to openrem/local_settings.py
• openrem/wsgi.py.example to openrem/wsgi.py

In the local_settings.py file, set the database details.

For testing you can use the SQLite3 database:

'ENGINE': 'django.db.backends.sqlite3',
'NAME': '/ENTER/PATH/WHERE/DB/FILE/CAN/GO',

• Linux example: 'NAME': '/var/openrem/openrem.db',
• Windows example: 'NAME': 'C:\Documents\User\OpenREM\openrem.db',

For production use, see Database options below

Generate a new secret key and replace the one in the local_settings.py file. You can use http://www.miniwebtool.com/django-secret-key-generator/ for this.

Create the database¶

• Linux: python /usr/lib/python2.7/dist-packages/openrem/manage.py syncdb
• Windows: python C:\Python27\Lib\site-packages\openrem\manage.py syncdb

Answer each question as it is asked, do setup a superuser. This username and password wil be used to log into the admin interface to create the usernames for using the web interface. See the Start using it! section below.

Help! I get a value too long for type character varying(50) error!

This error with part of the Django auth_permissions system that we are not using, and can safely be ignored. This is being tracked as Issue 62

For production installs, convert to South (What is south?)

• Linux: python /usr/lib/python2.7/dist-packages/openrem/manage.py convert_to_south remapp
• Windows: python C:\Python27\Lib\site-packages\openrem\manage.py convert_to_south remapp

Start test web server¶

• Linux: python /usr/lib/python2.7/dist-packages/openrem/manage.py runserver
• Windows: python C:\Python27\Lib\site-packages\openrem\manage.py runserver

If you are using a headless server and need to be able to see the web interface from another machine, use python /usr/lib/python2.7/dist-packages/openrem/manage.py runserver x.x.x.x:8000 (or Windows equivalent) replacing the x with the IP address of the server and 8000 with the port you wish to use.

Open the web addesss given, appending /openrem (http://localhost:8000/openrem)

Start using it!¶

Add some data! (See the Importing data to OpenREM for adding the scripts to the path if this doesn’t work)

• openrem_rdsr.py rdsrfile.dcm

Add some users (New in version 0.4.0)

• Go to the admin interface (eg http://localhost:8000/admin) and log in with the user created when you created the database (syncdb)

• Create some users and add them to the appropriate groups (if there are no groups, go to the OpenREM homepage and they should be created).

  • viewgroup can browse the data only
  • exportgroup can do as view group plus export data to a spreadsheet, and will be able to import height and weight data in due course (See Issue #21)
  • admingroup can delete studies in addition to anything the export group can do

Database options¶

SQLite is great for getting things running quickly and testing if the setup works, but is really not recommended for production use on any scale. Therefore it is recommended to use a different database such as PostgreSQL or MySQL.

Here are instructions for installing PostgreSQL on linux and on Windows:

Database migrations¶

South is a django application to manage database migrations. Using South means that future changes to the database model can be calculated and executed automatically with simple commands when OpenREM is upgraded.

Production webservers¶

Unlike the database, the production webserver can be left till later and can be changed again at any time.

For performance it is recommended that a production webserver is used instead of the inbuilt ‘runserver’. Popular choices would be either Apache or you can do as the cool kids do and use Gunicorn with nginx.

The django website has instructions and links to get you set up with Apache.

Virtualenv and virtualenvwrapper¶

If the server is to be used for more than one python application, or you wish to be able to test different versions of OpenREM or do any development, it is highly recommended that you use virtualenv or maybe virtualenvwrapper

Virtualenv sets up an isolated python environment and is relatively easy to use.

If you do use virtualenv, all the paths referred to in the documentation will be changed to:

• Linux: lib/python2.7/site-packages/openrem/
• Windows: Lib\site-packages\openrem

Advanced guides for developers¶

Installing Apache on Windows Server 2012 with auto-restart¶

Note

Author JA Cole

These instructions are for installing OpenREM under Apache on Windows as a developers alternative to the built-in HTTP server. They have been written using Windows Server 2012, and feature automatic restarts of the Apache server when the code changes, much as the built-in server does.

Get and Install Apache¶

• Download the zip of the appropriate version from https://www.apachelounge.com/
• Extract the zip somewhere useful. For this guide we will assume C:\apache24\

Get and Install MOD_WSGI¶

• Download mod_wsgi that matches your Windows, Apache and Python versions from http://www.lfd.uci.edu/~gohlke/pythonlibs/#mod_wsgi

• Extract the mod_wsgi.so file to C:\apache24\modules\

• Add the following module C:\apache24\conf\httpd.conf:

  LoadModule wsgi_module modules/mod_wsgi.so
  

• At the end of C:\apache24\conf\httpd.conf add the following:

  WSGIScriptAlias / "c:/Python27/Lib/site-packages/openrem/openrem/wsgi.py"
  WSGIPythonPath "c:/Python27/Lib/site-packages/openrem"
  
  <Directory "c:/Python27/Lib/site-packages/openrem/openrem">
  <Files wsgi.py>
  Order deny,allow
  Require all granted
  </Files>cd c:\py
  </Directory>
  

Get and Install wsgi.py and monitor.py¶

Detailed instructions are available here: https://code.google.com/p/modwsgi/wiki/ReloadingSourceCode

• Change wsgi.py in the openrem/openrem folder to the following

"""
WSGI config for OpenREM project.

This module contains the WSGI application used by Django's development server
and any production WSGI deployments. It should expose a module-level variable
named ``application``. Django's ``runserver`` and ``runfcgi`` commands discover
this application via the ``WSGI_APPLICATION`` setting.

Usually you will have the standard Django WSGI application here, but it also
might make sense to replace the whole Django WSGI application with a custom one
that later delegates to the Django one. For example, you could introduce WSGI
middleware here, or combine a Django application with an application of another
framework.

"""
import os
import sys

path = 'C:/Python27/Lib/site-packages/openrem'
if path not in sys.path:
sys.path.append(path)

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "openrem.settings")

# Apply WSGI middleware here.

import django.core.handlers.wsgi
application = django.core.handlers.wsgi.WSGIHandler()

import openrem.monitor
openrem.monitor.start(interval=1.0)

• Create a file monitor.py in the openrem/openrem folder with the following contents

# Code from the modwsgi wiki at https://code.google.com/p/modwsgi/wiki/ReloadingSourceCode
# Copyright 2007-2011 GRAHAM DUMPLETON
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#     http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#


import os
import sys
import time
import signal
import threading
import atexit
import Queue

_interval = 1.0
_times = {}
_files = []

_running = False
_queue = Queue.Queue()
_lock = threading.Lock()

def _restart(path):
    _queue.put(True)
    prefix = 'monitor (pid=%d):' % os.getpid()
    print >> sys.stderr, '%s Change detected to \'%s\'.' % (prefix, path)
    print >> sys.stderr, '%s Triggering Apache restart.' % prefix
    import ctypes
    ctypes.windll.libhttpd.ap_signal_parent(1)

def _modified(path):
    try:
        # If path doesn't denote a file and were previously
        # tracking it, then it has been removed or the file type
        # has changed so force a restart. If not previously
        # tracking the file then we can ignore it as probably
        # pseudo reference such as when file extracted from a
        # collection of modules contained in a zip file.

        if not os.path.isfile(path):
            return path in _times

        # Check for when file last modified.

        mtime = os.stat(path).st_mtime
        if path not in _times:
            _times[path] = mtime

        # Force restart when modification time has changed, even
        # if time now older, as that could indicate older file
        # has been restored.

        if mtime != _times[path]:
            return True
    except:
        # If any exception occured, likely that file has been
        # been removed just before stat(), so force a restart.

        return True

    return False

def _monitor():
    while 1:
        # Check modification times on all files in sys.modules.

        for module in sys.modules.values():
            if not hasattr(module, '__file__'):
                continue
            path = getattr(module, '__file__')
            if not path:
                continue
            if os.path.splitext(path)[1] in ['.pyc', '.pyo', '.pyd']:
                path = path[:-1]
            if _modified(path):
                return _restart(path)

        # Check modification times on files which have
        # specifically been registered for monitoring.

        for path in _files:
            if _modified(path):
                return _restart(path)

        # Go to sleep for specified interval.

        try:
            return _queue.get(timeout=_interval)
        except:
            pass

_thread = threading.Thread(target=_monitor)
_thread.setDaemon(True)

def _exiting():
    try:
        _queue.put(True)
    except:
        pass
    _thread.join()

atexit.register(_exiting)

def track(path):
    if not path in _files:
        _files.append(path)

def start(interval=1.0):
    global _interval
    if interval < _interval:
        _interval = interval

    global _running
    _lock.acquire()
    if not _running:
        prefix = 'monitor (pid=%d):' % os.getpid()
        print >> sys.stderr, '%s Starting change monitor.' % prefix
        _running = True
        _thread.start()
_lock.release()

Install Micosoft C++ Distributable¶

Install the microsoft C++ distributable making sure the version number matches the version number for the apache and mod_wsgi downloads. http://www.microsoft.com/en-us/download/details.aspx?id=30679#

Optional: Install apache as a service¶

Run a terminal as administrator.:

c:\apache24\bin\httpd -k install

Setup the URLs¶

Add the following to the openrem urls.py file:

from django.conf import settings
if settings.DEBUG:
    urlpatterns += patterns('django.contrib.staticfiles.views',
        url(r'^static/(?P<path>.*)$', 'serve'),
    )

Collect the static files¶

Collect your static files by running:

python manage.py collectstatic

If this fails because openrem lacks a static folder either copy the static folder from remapp to the openrem directory, adjust the openrem settings or set up a link. To setup a link run:

mklink /D c:\python27\lib\site-packages\openrem\static c:\python27\lib\site-packages\openrem\remapp\static

Version specific information¶

OpenREM Release Notes version 0.4.2¶

Headline changes¶

• This release fixes a major bug introduced in 0.4.0 regarding the import scripts.

Specific upgrade instructions¶

Upgrading from 0.4.1 or 0.4.0¶

Follow the Generic upgrade instructions

Upgrading from 0.3.9 or earlier¶

Follow the instructions in OpenREM Release Notes version 0.4.0

OpenREM Release Notes version 0.4.1¶

Headline changes¶

• This release is exacly the same as 0.4.1 bar some documentation corrections

Specific upgrade instructions¶

Please use the 0.4.0 release notes for upgrades from 0.3.9

OpenREM Release Notes version 0.4.0

OpenREM Release Notes version 0.4.0¶

Headline changes¶

• User authentication has been added
• Studies can be deleted from the web interface
• Import scripts can now be passed a list of files, eg python openrem_rdsr.py *.dcm
• Date of birth no longer retained for mammography (bug fix - correct behaviour already existed for other imports)
• General bug fixes to enable import from wider range of sources
• Improved user documentation

Specific upgrade instructions¶

• pip install openrem -U Note - this will upgrade openrem and all its dependencies.

• Migrate the database

  Warning

  A database migration is required that will need a choice to be made

  • Linux: python /usr/lib/python2.7/dist-packages/openrem/manage.py schemamigration --auto remapp
  • Windows: C:\Python27\Lib\site-packages\openrem\manage.py schemamigration --auto remapp

  When South has considered the changes to the schema, you will see the following message:

  ? The field 'Observer_context.device_observer_name' does not have a default specified, yet is NOT NULL.
  ? Since you are making this field nullable, you MUST specify a default
  ? value to use for existing rows. Would you like to:
  ?  1. Quit now.
  ?  2. Specify a one-off value to use for existing columns now
  ?  3. Disable the backwards migration by raising an exception; you can edit the migration to fix it later
  ? Please select a choice: 3
  

  As per the final line above, the correct choice is 3. The fields that are now nullable previously weren’t. Existing data in those fields will have a value, or those tables don’t exist in the current database. The problem scenario is if after the migration these tables are used and one of the new nullable fields is left as null, you will not be able to migrate back to the old database schema without error. This is not something that you will want to do, so this is ok.

  Do the migration:

  • Linux: python /usr/lib/python2.7/dist-packages/openrem/manage.py migrate remapp
  • Windows: C:\Python27\Lib\site-packages\openrem\manage.py migrate remapp

• Update the settings files

  Warning

  The settings file has changed and will need to be manually edited.

  Changes need to be made to the settings.py file where the database details are stored. Normally upgrades don’t touch this file and the copy in the upgrade has a .example suffix. This upgrade and potentially future ones will need to change this file, so the format has been changed. The settings.py file will now be replaced each time the code is upgraded. In addition, there is a new local_settings.py file that contains things that are specific to your installation, such as the database settings.

  This upgrade will include a file called settings.py.new and the local_settings.py.example file. You will need to do the following:

  • Copy the database settings from your current settings.py file to the local_settings.py.example file and rename it to remove the .example. Both of these files are in the openrem/openrem directory, which will be somewhere like
    • Linux: /usr/lib/python2.7/dist-packages/openrem/openrem/
    • Windows: C:\Python27\Lib\site-packages\openrem\openrem\
  • Move the existing settings.py out of the python directories
  • Rename the settings.py.new to settings.py

• Create a new secret key

  All versions of openrem ship with the same secret key. This key is used for web security checks, and should be unique (and secret) for each installation.

  • Generate a new secret key - http://www.miniwebtool.com/django-secret-key-generator/ is a suitable method of creating a new key.
  • Copy the new key and use it to replace the default key in the local_settings.py file

• Restart your webserver

• Add some users

  • Go to the admin interface (eg http://localhost:8000/admin) and log in with the user created when you originally created the database (manage.py syncdb)

  • Create some users and add them to the appropriate groups (if there are no groups, go to the OpenREM homepage and they should be created).

    • viewgroup can browse the data only
    • exportgroup can do as view group plus export data to a spreadsheet, and will be able to import height and weight data in due course (See Issue #21)
    • admingroup can delete studies in addition to anything the export group can do

Generic upgrade instructions¶

• Make sure you have setup South before you upgrade – see Database migrations for details.
• Always consult the specific version release notes linked above before upgrading.

Radiation Dose Structured Reports¶

• openrem_rdsr.py filename.dcm

For mammography DICOM images¶

• openrem_mg.py filename.dcm

The facility for extracting dose information from mammography DICOM images has been designed and tested with images created with the GE Senographe DS. It has now been tested in a limited fashion with the images generated by the following systems:

• GE Senographe Essential
• Hologic Selenia
• Siemens Inspiration

See Mammography module for testing restrictions.

For CT dose summary files from Philips CT scanners¶

• openrem_ctphilips.py filename.dcm

Patient height and weight information¶

If height and weight data is not available in the DICOM data, but is available from another source, then it can be imported into the database using the openrem_ptsizecsv.py function. Normally the key to match the size information with the studies in the database will be the accession number; however in some situations this isn’t available and the Study Instance UID can be used instead.

usage: openrem_ptsizecsv.py [-h] [-u] [-v] csvfile id height weight

-h, --help

Print the help text.

-u, --si-uid

Use Study Instance UID instead of Accession Number.

-v, --verbose

New in 0.3.7 Print to the standard output the success or otherwise of inserting each value.

csvfile

csv file containing the height and/or weight information and study identifier. Other columns will be ignored. Use quotes if the filepath has spaces.

id

Column title for the accession number or study instance UID. Use quotes if the title has spaces.

height

Column title for the patient height (DICOM size) - if this information is missing simply add a blank column with a suitable title. Use quotes if the title has spaces.

weight

Column title for the patient weight - if this information is missing simply add a blank column with a suitable title. Use quotes if the title has spaces.