Version 6 (modified by joshuadf, 9 years ago) (diff)


OpenClinica Quick Install on Ubuntu 8.04 LTS

This "quickstart" guide is a condensed version of the verbose instructions found in the OpenClinica download at install-docs/linux/install.txt. It should allow you to get OpenClinica installed on a fully updated install of Ubuntu 8.04 LTS in a short amount of time.

See also OpenclinicaFedora for installation on Fedora.

1. Download and install software.

1a. Install prerequisite software

# install Java separately first and agree to Sun license
aptitude -y install sun-java6-jdk
aptitude -y install tomcat5.5-admin
aptitude -y install postgresql postgresql-client

dpkg -l sun-java6-jdk tomcat5.5-admin postgresql
# Desired=Unknown/Install/Remove/Purge/Hold
# | Status=Not/Installed/Config-f/Unpacked/Failed-cfg/Half-inst/t-aWait/T-pend
# |/ Err?=(none)/Hold/Reinst-required/X=both-problems (Status,Err: uppercase=bad)
# ||/ Name                                  Version                     Description
# +++-=====================================-===========================-===============================================
# ii  postgresql                            8.3.8-0ubuntu8.04           object-relational SQL database (latest version)
# ii  sun-java6-jdk                         6-16-0ubuntu1.8.04          Sun Java(TM) Development Kit (JDK) 6
# ii  tomcat5.5-admin                       5.5.25-5ubuntu1.2           Java Servlet engine -- admin & manager web inte

1b. Download and extract OpenClinica for Linux

First we'll set up links so that both Red Hat's default OS tools and OpenClinica install.txt instructions will work. In short the downloads will live in /usr/local/oc/ while the live webapp and data will be visible as /usr/local/tomcat/ but really live in /var/lib/tomcat5/ per Linux Standard Base (LSB).

mkdir /var/lib/$TOMCAT/
chown tomcat55:adm /var/lib/$TOMCAT/
ln -s /var/lib/$TOMCAT/ /usr/share/$TOMCAT
ln -s /usr/share/$TOMCAT /usr/local/tomcat
mkdir /usr/local/oc

Next Register at and get OpenClinica 2.5.8 (09/02/2009), or browse for the latest version at the OpenClinica Downloads website.

Upload your OpenClinica-*.tar.gz download to /usr/local/oc/ on your host with a command like rsync -vaz OpenClinica-*.tar.gz $LINUX_HOST:/usr/local/oc/.

Now, on your host, decompress the download. If you have older versions of OpenClinica you can first move them to an oldversions/ directory.

cd /usr/local/oc
tar zxvf OpenClinica-*.tar.gz 

Make sure you only have one /usr/local/oc/OpenClinica-* directory or some of the commands below will fail.

2. Setup software

2a. PostgreSQL

Prepare a strong password to use for the db user and run the following:

# switch to postgres user       
su - postgres
  createuser --no-superuser --no-createrole --no-createdb --pwprompt clinica
  # type a strong password and note it!
  createdb --owner=clinica openclinica 
  psql -d openclinica -f /usr/local/oc/OpenClinica-*/config/database/PostgreSQL/*/install/create_database_*_tables_with_data.sql
# test the connection from localhost -- type your strong password 
psql --user clinica --host localhost openclinica

2b. Tomcat

Below are several small Tomcat configuration changes, bugfixes, and workarounds:

# install postgresql JDBC driver per OpenClinica instructions
cp /usr/local/oc/OpenClinica-*/config/libraries/postgresql-8.1-405.jdbc3.jar /usr/local/tomcat/common/lib/

By default, Tomcat is not configured for encrypted (HTTPS) requests. If you want to pass requests through an Apache httpd server, see ApacheConfig for details. Alternatively you can configure Tomcat to serve SSL requests by editing /etc/tomcat5.5/server.xml. First uncomment the Connector port="8443" section, then create a keystore with a self-signed certificate for Tomcat. Note that Firefox and other browsers will display a "This Connection is Untrusted" error with the self-signed certificate.

keytool -genkey -alias tomcat -keyalg RSA -dname "cn=Mark Jones, ou=JavaSoft, o=Sun, c=US" -storepass changeit -keypass changeit
mv /root/.keystore /usr/local/tomcat/

/etc/init.d/tomcat5.5 restart
# verify it is now running
netstat -anp |grep 8443
# tcp        0      0 :::8443                     :::*                        LISTEN      581/java            


2c. OpenClinica Deployment

# pre-deploy the WAR; we will edit some files before restarting Tomcat
cp /usr/local/oc/OpenClinica-*/distribution/OpenClinica.war /usr/local/tomcat/webapps 

Lastly, in /usr/local/tomcat/conf/Catalina/localhost/OpenClinica.xml change the JDBCRealm and SQLPostgres password lines for the "clinica" user to your db password and then run

# change OpenClinica settings
rsync -az $PROP /usr/local/oc/
sed -i 's;*;;' $PROP
sed -i 's;adminEmail=.*;adminEmail=you@your.domain;' $PROP
nano $PROP # change your clinica DB password
/etc/init.d/tomcat6-jsvc restart

Now go to https://localhost:8443/OpenClinica/MainMenu (root/12345678) and enjoy! If you cannot log in, check the log files in /usr/local/tomcat/logs/ for details.

Debugging OpenClinica

There are many places to find logs of errors occurring in OpenClinica. Ideally users will see helpful messages, but sometimes it is a generic message. For example, one of our users had a created a CRF with different RESPONSE_OPTIONS_TEXT columns, but identical RESPONSE_LABEL columns. When trying to preview the CRF, OpenClinica simply output "An error has occurred in the application."

I found the following message in the tomcat log /usr/local/tomcat/logs/catalina.out:

  Can't find resource for bundle java.util.PropertyResourceBundle, key resp_label_with_different_resp_values_html_error

I searched for the internationalization properties files in the webapp

grep -lrsi resp_label /usr/local/tomcat/webapps/OpenClinica/

I found the default file at /usr/local/tomcat/webapps/OpenClinica/WEB-INF/classes/org/akaza/openclinica/i18n/ and edited it with a text editor to add the resp_label_with_different_resp_values_html_error key:

resp_label_with_different_resp_options=RESPONSE_OPTIONS_TEXT can not be different for the same RESPONSE_LABEL. Error on row
resp_label_with_different_resp_values=REPONSE_VALUES can not be different for the same RESPONSE_LABEL. Error on row
resp_label_with_different_resp_values_html_error=REPONSE_VALUES can not be different for the same RESPONSE_LABEL. Error on row

You may also want to read about query debugging at our PostgreSql page.