How to Install an OpenTrials Instance

Install pre-requisites

Before installing the OpenTrials application, install the software listed below.

Server software

software	product URL	installation method	Debian/Ubuntu package name
Python (2.5, 2.6 or 2.7)	http://www.python.org/	OS package manager	python2.7
python2.x-dev (2.5, 2.6 or 2.7)	http://www.python.org/	OS package manager	python2.7-dev
GNU compiler and tools	http://www.python.org/	OS package manager	build-essential
libxml2-dev - XML processing library	http://xmlsoft.org/	OS package manager	libxml2-dev
libxslt1-dev - XSLT processing library	http://xmlsoft.org/XSLT	OS package manager	libxslt1-dev
Apache HTTP server 2.2	http://httpd.apache.org/	OS package manager	apache2
mod_wsgi - Python adapter	http://code.google.com/p/modwsgi/	OS package manager	libapache2-mod-wsgi
MySQL 5.1 database server	http://dev.mysql.com/	OS package manager	mysql-server-5.1
MySQL 5.1 client dev. library	http://dev.mysql.com/	OS package manager	libmysqlclient-dev
Git 1.7	http://git-scm.com/	Version control system	OS package manager	git

1. Install each package below using the recommended installation method above.

Note: Python comes pre-installed in most Linux distributions. If Python 2.5 or 2.6 is already installed, there is no need to install a newer version.

Note2: on Ubuntu 10.04 (Lucid) build-essential includes: dpkg-dev, g++, libc6-dev and make

The commands for Ubuntu 10.10 through 11.10 are:

$ sudo apt-get install build-essential python2.7 python2.7-dev libxml2-dev libxslt1-dev
$ sudo apt-get install apache2 libapache2-mod-wsgi 
$ sudo apt-get install mysql-server-5.1 libmysqlclient-dev
$ sudo apt-get install git subversion

System-wide Python libraries

software	product URL	installation method
distribute 0.6	http://pypi.python.org/pypi/distribute	sudo python distribute_setup.py
virtualenv	http://pypi.python.org/pypi/virtualenv	sudo easy_install virtualenv

2. Download the distribute_setup.py script and use the installed Python interperter to run it as root (this provides the easy_install utility)

$ wget http://python-distribute.org/distribute_setup.py
$ sudo python distribute_setup.py

3. Use easy_install to download and install virtuaenv (replace the version number with the version number of the Python interpreter you used to perform step 2 above; here we used 2.7)

$ sudo easy_install-2.7 virtualenv

The pip utility, used to install further Python packages is part of virtualenv, and available whenever a virtualvenv is activated, which we will do in step 5.

Configure the database

4. Create a database user and a opentrials database. The user name and password will be used in step 9 below.

• The database user must have all privileges on the opentrials database
• The database user should have CREATE DATABASE privileges, to run the automated tests (step 12)

Log in to the MySQL shell as root:

$ sudo mysql -p

Run the following commands in the MySQL shell (you may copy, paste and edit as needed):

CREATE DATABASE opentrials; 
CREATE USER 'tester'@'localhost' IDENTIFIED BY 'puffpuff';
GRANT ALL PRIVILEGES ON opentrials.* TO 'tester'@'localhost';

To run the automated tests, a test database must also be configured:

CREATE DATABASE test_opentrials; 
GRANT ALL PRIVILEGES ON test_opentrials.* TO 'tester'@'localhost';

Install the application environment

Note: all of the remainig steps can be performed by a regular user without root access.

5. Use virtualenv to create an application environment and activate it:

$ virtualenv --distribute opentrials-env
$ source opentrials-env/bin/activate
(opentrials-env)$   # note that the shell prompt displays the active virtual environment

Installing version dependent libraries

6. Clone and install Haystack v1.2.4

(opentrials-env)$ git clone git://github.com/toastdriven/django-haystack.git
(opentrials-env)$ cd django-haystack
(opentrials-env)$ git checkout v1.2.4
(opentrials-env)$ python setup.py install
(opentrials-env)$ cd ..

7. Clone and instal Django Fossil

(opentrials-env)$ git clone git://github.com/bireme/django-fossil.git
(opentrials-env)$ cd django-fossil
(opentrials-env)$ python setup.py install
(opentrials-env)$ cd ..

Download the OpenTrials application

8. Create an installation directory and check out the application source from the trunk or a tag into it:

(opentrials-env)$ git clone git://github.com/bireme/opentrials.git opentrials-git

9. Install opentrials and its dependencies:

(opentrials-env)$ cd opentrials-git
(opentrials-env)$ pip install -r requirements.txt 

(opentrials-env)$ cd ..
(opentrials-env)$ ln -s opentrials-git/opentrials/

(opentrials-env)$ cd opentrials
(opentrials-env)$ mkdir -p static/attachments

When installing opentrials, the install script will also install the following dependencies:

Django 1.2.3	http://www.djangoproject.com/download/
MySQLdb 1.2.2	http://sourceforge.net/projects/mysql-python/files/
lxml 2.2.5	http://codespeak.net/lxml
south	http://south.aeracode.org/
django_nose	http://github.com/jbalogh/django-nose
django_rosetta	http://code.google.com/p/django-rosetta/
django-plus	http://code.google.com/p/django-plus/
BeautifulSoup	http://www.crummy.com/software/BeautifulSoup
django-compressor	https://github.com/mintchaos/django_compressor
python-markdown	http://www.freewisdom.org/projects/python-markdown
django-fossil	http://reddes.bvsalud.org/projects/clinical-trials/browser/sandbox/django-fossil
django-haystack 1.2.4	http://haystacksearch.org
pysolr	http://github.com/toastdriven/pysolr

10. Make the manage.py script executable

(opentrials-env)$ chmod +x manage.py

11. Create the settings_local.include by copying settings_local.include-SAMPLE and editing the configurations. Most settings in settings_local.include may be used as is, but at least the database and e-mail host user and passwords must be changed. Search for the text "PASSWORD" (no quotes) in the file to see where to change.

(opentrials-env)$ cp settings_local.include-SAMPLE settings_local.include 
(opentrials-env)$ vi settings_local.include   # edit the database settings etc.

(to fioCruz: go to HowToInstallFioCruz)

12. Create database tables, load initial data and update migrations

(opentrials-env)$ ./manage.py syncdb --all
(opentrials-env)$ ./manage.py migrate --fake

13. Run the development server to manually test the application instance

(opentrials-env)$ ./manage.py runserver

If you want to access the development server from a remote machine, provide the server IP and port arguments, for example:

(opentrials-env)$ ./manage.py runserver 172.17.1.54:8000 # replace the IP

14. Give write permissions to the apache user in the following directories (if they don't exist, create them):

Default instance:

static/compressor-cache
static/backup
static/attachments

Instance customized for www.ensaiosclinicos.gov.br:

custom/ecgovbr/static/compressor-cache
custom/ecgovbr/static/backup
custom/ecgovbr/static/attachments

Advanced Search Configuration

In order to enable advanced search functionality, OpenTrials makes use of Solr/Lucene search server. Instructions on how to install a Solr instance can be found at http://lucene.apache.org/solr/

1. Install Solr

(opentrials-env)$ sudo apt-get install solr-tomcat

2. Copy the Solr schema file, shipped with opentrials source, from solr/schema.xml to your local Solr instance (probably will need root privileges). It can be found at '/etc/solr/conf/'

(opentrials-env)$ sudo cp solr/schema.xml path/to/my/solr/schemafiles/

3. Restart your Solr instance

(opentrials-env)$ sudo service tomcat6 restart  #ubuntu example

4. Edit the settings_local.include to configure Solr server URL

### Solr integration for advanced search
HAYSTACK_SOLR_URL = 'http://127.0.0.1:8080/solr'   

4. Follow the instructions describe on http://reddes.bvsalud.org/projects/clinical-trials/wiki/HowToIndex to maintain the search functionality.

Development environment

Note: the following packages are not required for testing and production servers.

If you intend to contribute code or translations to this project, you should also install:

software	purpose	product URL	installation method
docutils 0.6	http://pypi.python.org/pypi/docutils/	pip install docutils
GNU gettext-runtime 0.17	UI translation	http://www.gnu.org/software/gettext/	OS package manager
PyYAML 3.0	YAML parsing (*) http://pyyaml.org/wiki/PyYAML	pip install pyyaml
Markdown 2.0	plaintext markup rendering (*)	http://pypi.python.org/pypi/Markdown/	pip install markdown
Textile 2.1.3	plaintext markup rendering (*)	http://pypi.python.org/pypi/textile	pip install textile

Note: the packages marked (*) above are required to run the full suite of tests that come with Django

To generate data model diagrams, you will need:

PIL 1.1.7	imaging library	http://www.pythonware.com/products/pil/	pip install pil
graphviz 2.20	diagram rendering	http://www.graphviz.org/	OS package manager
django-graphviz 0.1	ER-diagram rendering	http://code.google.com/p/django-graphviz/	unzip and softlink to django-env/lib/python2.6/site-packages

The commands to generate a data model diagram are:

(opentrials-env)$ ./manage.py modelviz repository > repository.dot
(opentrials-env)$ dot -Tpng -orepository.png repository.dot 

To compile the translation files:

(opentrials-env)$ ./manage.py compilemessages

Emulating the BIREME deployment setting

The BIREME ITI team currently deploys the Clinical Trials application root at:

/home/aplicacoes-bvs/rebrac-alfa/opentrials/

The directory above is where the settings.py file is located. In order to emulate this environment, developers may want to create a /home/aplicacoes-bvs in their local machine, and create a link to the checkout, like this:

/home/aplicacoes-bvs$ sudo ln -s /home/your-name/prj/ct/svn/trunk rebrac-alfa

Configuring webserver

Configuring Apache Webserver

A sample of the httpd.conf file can be found in https://github.com/bireme/opentrials/blob/master/opentrials/apache/httpd-devel.conf

A sample of the WSGI file can be found in https://github.com/bireme/opentrials/blob/master/opentrials/apache/app/devel.wsgi

SMTP configuration

For configure the e-mail sender the following parameters must be changed in the file {{setting_local.include}}:

https://github.com/bireme/opentrials/blob/master/opentrials/settings_local.include-SAMPLE

EMAIL_HOST = 'your.email.host.com'
EMAIL_PORT = 25
EMAIL_HOST_USER = 'youremailuser@blah.com'
EMAIL_HOST_PASSWORD = '******'

Troubleshooting

mysql-python

The mysql-python package used to install OK with pip install on several Linux distributions prior to Oct. 2009, but in Ubuntu 9.10 it can't compile itself because of a "EnvironmentError: mysql_config not found".

The file mysql_config is part of the libmysqlclient-dev package, but even if that package is installed and the file is present, the mysql-python installation script can't find it.

Work around

To fix:

0) Check that you have the required packages for compiling Python extensions written in C. In Ubuntu, the required packages for Python 2.5 are (you may also use Python 2.6)::

  (opentrials-env)$ sudo apt-get install build-essential python2.5-dev

1) Check that you have the required MySql libraries:

  (opentrials-env)$ sudo apt-get install mysql-client libmysqlclient-dev

2) Download and unpack the mysql-python source package, currently it is:

  (opentrials-env)$ wget http://pypi.python.org/packages/source/M/MySQL-python/MySQL-python-1.2.3c1.tar.gz

3) Edit the file MySQL-python-1.2.3c1/site.cfg

Search for: mysql_config = /

Uncomment and edit the line defining "mysql_config = " to the actual location of the mysql_config file. In Ubuntu 9.10 (64 bits) it is:

mysql_config = /usr/bin/mysql_config

4) Build it using setup.py:

  (opentrials-env)$ python setup.py install