HOWTO: install Indivo X

From Indivo

Jump to: navigation, search

Contents

[edit] Defaults

This document sets up the Indivo backend server and Indivo UI server on the same machine. The backend server runs on port 8000, the UI server on port 80 by default. This is configurable by changing the appropriate port numbers in the instructions below.

This document is up-to-date for Indivo X Beta 3 (0.9.3). Please check the Indivo X Beta 3 (0.9.3) Release Notes.

[edit] Pre-Requisites

This documents the installation of a complete Indivo X server and user interface. For concreteness, we show all of the exact instructions needed when installing on Ubuntu Linux 10.10 (Maverick) or 11.04 (Natty). We welcome variants of these explicit instructions from folks installing on other operating systems, we will be happy to post them alongside these instructions.

  • Recent Linux installation (Kernel 2.6+)
  • Note: We recommend you do this by sudo'ing from a non-root user. If you would like to do this as root make sure you create at least one non-root user with `useradd -m {USER}` otherwise the default locale will not be set. This issue is most common on a new OS build.
  • PostgreSQL 8.3+ (8.4 recommended and the default on Ubuntu 10.10) 
apt-get install postgresql
  • Python 2.6 (NOT 2.5 or below) with packages: lxml and psycopg2 
apt-get install python-psycopg2 python-lxml
  • Django 1.2 (1.1 is supported, but some tests will not run without 1.2)

On Ubuntu 10.04 or earlier: 

wget http://www.djangoproject.com/download/1.2.5/tarball/
tar xzvf Django-1.2.5.tar.gz
cd Django-1.2.5
sudo python setup.py install
cd ..
rm -rf Django-1.2.5 Django-1.2.5.tar.gz

On Ubuntu 10.10 or later: 

apt-get install python-django
  • Apache 2 (for production) with module mod_wsgi (mod_ssl for HTTPS is strongly recommended for production, but we won't cover its installation here.) 
apt-get install apache2-mpm-prefork
  • NOTE: For Lucid, you may need to do an apt-get update before making the following command: 
apt-get install libapache2-mod-wsgi
  • easy_install for Python 
apt-get install python-setuptools
  • the Django South DB migration library. 
easy_install South
  • Python Markdown support 
easy_install Markdown

[edit] Setup Database

You'll have the easiest time naming your database indivo

  • There are two ways to authenticate to PostgreSQL: use your Unix credentials, or use a separate username and password. We strongly recommend the latter, and our instructions are tailored appropriately. If you know how to use PostgreSQL and want to use Unix-logins, go for it, just remember that when you use Apache, it will usually try to log in using its username, www-data.
  • in /etc/postgresql/8.4/main/pg_hba.conf, find the line that reads: 
 local     all     all        ident

This should be the second uncommented line in your default config. Change ident to md5: 

 local     all     all        md5

You will need to restart PostgreSQL: 

service postgresql-8.4 restart
  • Create a PostgreSQL user for your Indivo service, e.g. "indivo" and setup a password 
su - postgres
createuser --superuser indivo
psql
postgres=# \password indivo
  • Create the Database and make the Indivo user its owner. 
createdb -U indivo -O indivo indivo

[edit] Download, Install, and Configure Indivo Backend Server

[edit] From A Packaged Release

  • Download the latest release of Indivo X (see Releases) and untar into indivo_server/. Do not change this directory name--it will break the django settings file.

[edit] From Github (Development Version)

  • From the commandline, run: 
cd /desired/install/directory
git clone git://github.com/chb/indivo_server.git
cd indivo_server
git submodule init
git submodule update
  • If you want to run the bleeding edge version of Indivo, you're done. If you want to use an official release, you can list releases with: 
 git tag -n1

and checkout your desired release with: 

git checkout {TAGNAME}

where tagname might be (i.e., for beta 3) v0.9.3.0

[edit] Configuration

  • Copy settings.py.default to settings.py, and open it up. Make sure to look at the 'Required Setup' settings, and examine 'Advanced Setup' if you are interested. As an absolute minimum, update the following:
    • set DATABASE_USER to the username you chose, in this documentation web, and set DATABASE_PASSWORD accordingly.
    • set APP_HOME to the complete path to the location where you've installed indivo_server, e.g. /web/indivo_server
    • set SITE_URL_PREFIX to the URL where your server is running, including port number e.g. https://pchr.acme.com:8443
    • set the EMAIL_* parameters appropriately for sending out emails.
    • set the SEND_MAIL parameter to True or False depending on whether you want emails actually being sent.
    • set SECRET_KEY to a unique value, and don't share it with anybody
  • Under utils/ copy indivo_data.xml.default to indivo_data.xml and edit accordingly. Note: Make sure to do this step before resetting the database, as the credentials for users/apps in indivo_data.xml cannot be changed without an additional reset of the database.

[edit] Resetting the Database

  • Run utils/reset.sh with some combination of the following flags: 
-b Load bootstrap

-c Load coding systems

-s syncdb

For all, simply run: 

utils/reset.sh -bcs

You must run reset.sh before the accounts and applications you set up in indivo_data.xml exist.

[edit] Coding Systems

Indivo uses SNOMED CT for problem coding, HL7v3 for immunization coding, and LOINC for lab coding. Medication coding will likely use RxNorm. In most cases, the license on these coding systems does not allow us to redistribute these codes with Indivo. We don't like this. We wish we had truly free coding systems for health. We've told the folks at the National Library of Medicine as much. But there's not much we can do about this for now.

What we've done is make it easy for you to load coding systems into Indivo if you can get them independently. Get the HL7 v3 codes from hl7.org, get the SNOMED CT dataset from UMLS. You should see "|"-separated files. Examples of how these files are formatted can be found in codingsystems/data/sample. Once you've downloaded these files independently from the coding system agencies, copy them to:

  • codingsystems/data/complete/SNOMEDCT_CORE_SUBSET_200911_utf8.txt
  • codingsystems/data/complete/HL7_V3_VACCINES.txt
  • codingsystems/data/complete/LOINCDB.txt

Once that's done, assuming you've installed everything in /web/indivo_server, you can run 

utils/reset.sh -bcs

and have everything loaded properly.

See more info on codingsystems and where to find the data files here .

[edit] Database Cleanup

Each request made against Indivo Server generates some oauth-related data that is stored in the database for security reasons (for example, session tokens are stored whenever a user logs in, and oAuth Nonces are stored for every request). This data is only relevant for a certain duration (i.e., the length of a web session), after which point it becomes needless clutter in the database. In order to remove all such clutter, from APP_HOME run: 

python manage.py cleanup_old_tokens

This command should be set up to run as a cron job, and should be run regularly to make sure the size of the database doesn't get out of control (we recommend at least once a week, and more frequently for high traffic installations).

[edit] Testing Indivo Backend Server

Indivo uses the django-tests framework to provide some basic unit and API testing. If you want to make sure everything is setup properly before opening the server up to the network, running these tests is a good start. Django tests set up a clean test database for each run of the tests, so don't worry about your installation being corrupted. To run the Indivo tests, in APP_HOME run: 

 python manage.py test indivo

NOTE: Django tests have some version compatibility issues. In Django 1.1, testing of 'PUT' calls to the API are broken, so running the tests should result in some errors. In Django 1.2, one of the built-in tests fails unless the Django Auth module is installed. A working patch exists here.

[edit] Download, Install, and Configure UI Server

[edit] From A Packaged Release

  • Download the latest release of Indivo X UI Server (see Releases) and untar into indivo_ui_server/. Do not change this directory name--it will break the django settings file.

[edit] From Github (Development Version)

  • From the commandline, run: 
cd /desired/install/directory
git clone git://github.com/chb/indivo_ui_server.git
cd indivo_ui_server
git submodule init
git submodule update
  • If you want to run the bleeding edge version of Indivo, you're done. If you want to use an official release, you can list releases with: 
 git tag -n1

and checkout your desired release with: 

git checkout {TAGNAME}

where tagname might be (i.e., for beta 3) v0.9.3.0

[edit] Configuration

  • Copy settings.py.default to settings.py, and update a few key parameters:
    • set SERVER_ROOT_DIR to the complete filesystem path to the location where you've installed indivo_ui_server, e.g. /web/indivo_ui_server, with no trailing slash.
    • set INDIVO_UI_SERVER_BASE to the URL at which your UI server will be accessible, e.g. http://localhost, with no trailing slash.
    • set INDIVO_SERVER_LOCATION, CONSUMER_KEY, CONSUMER_SECRET appropriately to match the Indivo Server's location and chrome credentials (check indivo_server/utils/indivo_data.xml BEFORE you reset the database on the indivo_server end).
    • set SECRET_KEY to a unique value, and don't share it with anybody
  • If there isn't an empty sessions directory under indivo_ui_server/, create it with mkdir sessions

[edit] Running the Development Servers

The Django development servers are easy to run at the prompt.

The backend server can run on localhost in the configuration given above: 

cd /web/indivo_server/
python manage.py runserver 8000

The UI server, if you want it accessible from another machine, needs to specify a hostname or IP address. If you want port 80, you need to be root of course: 

cd /web/indivo_ui_server/
python manage.py runserver HOSTNAME:80

IMPORTANTLY, if you've installed Apache, you'll need to turn it off to run your UI server from the prompt: 

/etc/init.d/apache2 stop

[edit] Running on Apache

Assuming you installed Indivo Server and UI in /web, the steps to getting Apache2 serving Indivo and its UI are:

  • in /etc/apache2/sites-available/default, add: 
<VirtualHost *:8000>
  ServerAdmin YOU@localhost
  ServerName localhost
  DocumentRoot /web/indivo_server
  Alias /static/ /web/indivo_server/static/
  EnableMMAP On
  EnableSendfile On
  LogLevel warn

  <Directory /web/indivo_server>
     Order deny,allow
     Allow from all
  </Directory>

  WSGIApplicationGroup %{GLOBAL}
  WSGIScriptAlias / /web/indivo_server/django.wsgi
  WSGIPassAuthorization On
</VirtualHost>

<VirtualHost *:80>
  ServerAdmin YOU@localhost
  ServerName localhost
  DocumentRoot /web/indivo_ui_server
  Alias /static/ /web/indivo_ui_server/ui/static/
  EnableMMAP On
  EnableSendfile On
  LogLevel warn

  <Directory /web/indivo_ui_server>
   Order deny,allow
   Allow from all
  </Directory>

  WSGIDaemonProcess indivo_ui user=www-data group=www-data processes=1 maximum-requests=500 threads=10
  WSGIScriptAlias / /web/indivo_ui_server/django.wsgi
  WSGIPassAuthorization On
</VirtualHost>

In our experience, using WSGIProcessGroup directive with a specific group (not global), even when it matches the WSGIDaemonProcess group name (i.e. indivo_ui), can cause a permission issue with reading the Unix socket. We will continue to investigate this issue. However, due to incompatibilities between the lxml package and mod_wsgi, it is necessary to set Indivo Server to the global WSGIProcessGroup instead of running daemons.

  • make sure ports.conf has: 
   NameVirtualHost *:80
   Listen 80
   Listen 8000
  • make sure that www-data (or whoever is in /etc/apache2/envvars) has access to indivo_server and indivo_ui_server AND can write to indivo_server/indivo.log and indivo_ui_server/sessions/*, including the sessions/ directory itself.
    • since you probably did a python manage.py syncdb, you almost certainly want to just remove the current indivo.log before you move ahead.
  • really, have you checked this www-data permission issue? This will be the cause of all your problems if you don't check this carefully.
  • check your /etc/apache2/sites-enabled/000-default file again and make sure that your Alias /static/ lines match the above example exactly
  • restart Apache: 
 service apache2 restart

[edit] What Next?

You should be able to log in and add the default apps. These apps are purposely limited in functionality. May the best apps win.

[edit] BEFORE YOU RUN THIS IN PRODUCTION

This is the second public beta, which means we think it's ready to be used in production by knowledgeable early adopters. We've done a good amount of security testing, but we'll be doing more.

In other words, we think it's now reasonable to plan for releasing Indivo X in production, but we don't recommend rushing it out without care.

Retrieved from "http://wiki.chip.org/indivo/index.php/HOWTO:_install_Indivo_X"
Personal tools
Navigation