How to Install an OpenTrials Instance

Install pre-requisites

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

Server software

softwareproduct URLinstallation methodDebian/Ubuntu package name
Python (2.5, 2.6 or 2.7) OS package manager python2.7
python2.x-dev (2.5, 2.6 or 2.7) OS package manager python2.7-dev
GNU compiler and tools OS package manager build-essential
libxml2-dev - XML processing library OS package manager libxml2-dev
libxslt1-dev - XSLT processing library OS package manager libxslt1-dev
Apache HTTP server 2.2 OS package manager apache2
mod_wsgi - Python adapter OS package manager libapache2-mod-wsgi
MySQL 5.1 database server OS package manager mysql-server-5.1
MySQL 5.1 client dev. library OS package manager libmysqlclient-dev
Git 1.7 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

softwareproduct URLinstallation method
distribute 0.6 sudo python
virtualenv sudo easy_install virtualenv

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

$ wget
$ sudo python

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://
(opentrials-env)$ cd django-haystack
(opentrials-env)$ git checkout v1.2.4
(opentrials-env)$ python install
(opentrials-env)$ cd ..

7. Clone and instal Django Fossil

(opentrials-env)$ git clone git://
(opentrials-env)$ cd django-fossil
(opentrials-env)$ python 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:// 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
MySQLdb 1.2.2
lxml 2.2.5
django-haystack 1.2.4

10. Make the script executable

(opentrials-env)$ chmod +x

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)$ ./ syncdb --all
(opentrials-env)$ ./ migrate --fake

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

(opentrials-env)$ ./ runserver

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

(opentrials-env)$ ./ runserver # replace the IP

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

Default instance:


Instance customized for


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

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

4. Follow the instructions describe on 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:

softwarepurposeproduct URLinstallation method
docutils 0.6 pip install docutils
GNU gettext-runtime 0.17 UI translation OS package manager
PyYAML 3.0 YAML parsing (*) pip install pyyaml
Markdown 2.0 plaintext markup rendering (*) pip install markdown
Textile 2.1.3 plaintext markup rendering (*) 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 pip install pil
graphviz 2.20 diagram rendering OS package manager
django-graphviz 0.1 ER-diagram rendering unzip and softlink to django-env/lib/python2.6/site-packages

The commands to generate a data model diagram are:

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

To compile the translation files:

(opentrials-env)$ ./ compilemessages

Emulating the BIREME deployment setting

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


The directory above is where the 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

A sample of the WSGI file can be found in

SMTP configuration

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




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

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

  (opentrials-env)$ python install