How to Install an OpenTrials Instance

Install pre-requisites

Before installing the OpentTrials? application, install the software listed below.

Server software

software	product URL	installation method	Debian/Ubuntu package name
Python 2.5 or 2.6	http://www.python.org/	OS package manager	python2.6
python2.x-dev (2.5 or 2.6)	http://www.python.org/	OS package manager	python2.6-dev
GNU compiler and tools	http://www.python.org/	OS package manager	build-essential
Apache HTTP server 2.2	http://httpd.apache.org/	OS package manager	apache2
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	libmysqlclient15-dev
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
mod_wsgi - Python adapter	http://code.google.com/p/modwsgi/	OS package manager	libapache2-mod-wsgi

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

System-wide Python libraries

software	product URL	installation method
distribute 0.6.10	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
# python distribute_setup.py

3. Use easy_install to download and install virtuaenv

# easy_install virtualenv

Configure the database

4. Create a database user and a opentrials database. The user name and password will be used in step 10 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

Paste this code in the MySQL shell:

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 --no-site-packages django-env
$ source django-env/bin/activate
(django-env)$   # note that the shell prompt displays the active virtual environment

6. With the django-env environment active, use easy_install to download and install the remaining packages:

Django 1.2.1	http://www.djangoproject.com/download/	easy_install django
MySQLdb 1.2.2	http://sourceforge.net/projects/mysql-python/files/	easy_install mysql-python (see Troubleshooting)
lxml 2.2.5	http://codespeak.net/lxml	easy_install lxml
django_nose	http://pypi.python.org/pypi/django-nose/0.1.2	easy_install django-nose

(django-env)$ easy_install django
(django-env)$ easy_install mysql-python
(django-env)$ easy_install lxml

Download the Clinical Trials Repository application

7. Go to a suitable installation directory and check out the application source

(django-env)$ svn co http://svn.reddes.bvsalud.org/clinical-trials/trunk/opentrials

8. Make the manage.py script executable

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

9. Create the settings_local.py and edit the configurations as needed

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

10. Create database tables and load initial data

(django-env)$ ./manage.py syncdb

11. Run automated tests

(django-env)$ ./manage.py test

12. Run the test server to manually test the application instance

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

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/	easy_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	easy_install pyyaml
Markdown 2.0	plaintext markup rendering (*)	http://pypi.python.org/pypi/Markdown/	easy_install markdown
Textile 2.1.3	plaintext markup rendering (*)	http://pypi.python.org/pypi/textile	easy_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/	easy_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:

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

13. Compile the translation files

(django-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

Troubleshooting

mysql-python

The mysql-python package used to install OK with easy_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)::

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

1) Check that you have the required MySql libraries:

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

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

  (django-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:

  (django-env)$ python setup.py install