OpenClinica User Manual/Ubuntu10Upgrade

Introduction
I will not cover SSL setup or certificate generation, it's too long and is well explained elsewhere. What is more, if you upgrade as it is here indicated, you can use your already functioning setup.

First of all: BACKUP!

Yes, it is important. VERY!

The 3.1 DB structure differs from the 3.0, and during installation you may seriously mess it up, so a backup of the database is more than recommended, it's a must.

Backing up
sudo invoke-rc.d tomcat6 stop sudo rm -rf /var/lib/tomcat6/work/Catalina/localhost/OpenClinica/*
 * 1) Turn off Tomcat 6
 * 1) Remove last session data

cd mkdir -p oc/BACKUP sudo mv /var/lib/tomcat6/webapps/OpenClinica ./oc/BACKUP/ sudo cp -Rp /usr/share/tomcat6/openclinica.data/ ./oc/BACKUP/
 * 1) BACKUP OPENCLINICA

pg_dump openclinica > ./BACKUP/OC30-db-`date +%b-%d-%Y`.sql
 * 1) BACKUP THE DB
 * 1) Adjust to your needs. If your database is remote, log into the
 * 2) remote machine to do the dump.

Two words about my configuration that might be of use to some:

My OC installation is on 2 different virtual machines (VMs): one for the OC/tomcat server, one for a PostgreSQL database (there is actually a third machine where the database dumps are sent, for security backup, but that is not important for the moment.)

AFTER backing up, I took snapshots of the VMs so I could revert if everything went to hell.

Preparing packages
In the official instructions from OpenClinica for installation, they go into great details on the installation of Tomcat-JVSC from scratch... but that is not the Ubuntu way, that is not the Debian way.

The beauty of package management is that it allows ease of use and... well, management. So, out compile, in apt-get/aptitude/synaptic:

sudo add-apt-repository "deb http://archive.canonical.com lucid partner" sudo apt-get update
 * 1) First, add the partner repository, if you haven't already
 * 2) (This is mainly for the Java stuff)

sudo apt-get -y install python-software-properties sudo apt-get -y install sun-java6-jdk jsvc sudo update-java-alternatives -s java-6-sun sudo apt-get -y install tomcat6 sudo apt-get -y install libtcnative-1
 * 1) Then we add the software
 * 1) Approve the Java EULA: so not Open Source =(
 * 1) You also need apache APR, which you can find in
 * 1) This one you need to unzip the OpenClinica packs sudo apt-get install unzip

Installing the new version of the .war
cd mv $OPENCLINICA_ZIP ~/oc cd oc unzip OpenClinica-3.1*.zip cd OpenClinica-3.1.1-Community/distribution/ unzip OpenClinica.war -d OpenClinica sudo cp -Rp OpenClinica /var/lib/tomcat6/webapps/ sudo chown tomcat6. /var/lib/tomcat6/webapps/OpenClinica sudo mkdir /usr/share/tomcat6/openclinica.data sudo chown -R tomcat6. /usr/share/tomcat6/openclinica.data sudo ln -s /var/lib/tomcat6/openclinica.data /usr/share/tomcat6/openclinica.data sudo mkdir /usr/share/tomcat6/logs sudo chown tomcat6. /usr/share/tomcat6/logs sudo ln -s /var/lib/tomcat6/logs /usr/share/tomcat6/logs cd sudo cp -Rp ./oc/BACKUP/openclinica.data/* /usr/share/tomcat6/openclinica.data sudo chown tomcat6. /usr/share/tomcat6/openclinica.data
 * 1) Now, the fun part...
 * 1) If you have a previous installation, you should copy the content of
 * 2) your openclinica.data folder in /usr/share/tomcat6/openclinica.data

PostgreSQL actions

 * 1) PostgreSQL
 * 2) (do this in another machine if you want your DB to be separate)
 * 3) Skip these steps if you already have a functioning DB, specially
 * 4) if you're upgrading!

sudo apt-get -y install postgresql postgresql-client

sudo apt-get install pwgen
 * 1) This one is not required, but it helps out choosing passwords

pwgen 24 -s -1 > passwd_postgresql chmod 600 passwd_postgresql psql --user clinica --host localhost openclinica --password `cat passwd_postgresql`
 * 1) Generate the unbreakable password
 * 1) Make it user-only
 * 1) Create the database

Editing datainfo.properties
Insert the details of your configuration. Pay special attention to:
 * 1) BACK IN THE OpenClinica Machine
 * 2) Configuration file:
 * 3) ../OpenClinica/WEB-INF/classes/datainfo.properties

1/ Database password: in this example, passwd_postgresql

2/ Database location: defaults to, insert the IP or full domain name of the host if remote DB.

ATTENTION: In my case, I'm using a remote PostGreSQL over a SSL layer. Since the certificate is autosigned, some tweaking is necessary. In OC 3.0 my URL was:

url=jdbc:postgresql://xxx.xxx.xxx.xxx:5432/openclinica?ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory&

The new configuration file changes the variable to:

db=${WEBAPP.lower}?ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory&

3/ For ease of use, I changed the following variable too: log.dir=${catalina.home}/logs/${WEBAPP.lower}

Editing Java settings for Tomcat
In hindsight†, my Tomcat was running out of memory, so it would be a good idea at this point to increase Java's available memory: cd /usr/share/tomcat6/bin/ sudo cp setenv.sh setenv-`date +%b-%d-%Y`.sh

sudo vim setenv.sh I changed mine to:
 * 1) Edit setenv.sh with your favourite vim ;)

cd

† This "hindsight" means that AFTER the upgrade, OC311 started normally, only to freeze after a few minor tests with a PermMemory exceeded error. This froze OC, Tomcat and Apache alltogether. Not cool!

AND NOW...
The anticipated moment!

(It's a good idea to keep an eye on Tomcat while loading, so...) sudo invoke-rc.d tomcat6 start && \ tail -n100 -f /var/lib/tomcat6/logs/catalina.out

IF everything went according to plan, then you should:

1/ see a slow startup, since the new application has to deploy ...

after a while

...

2/ you should start to see A LOT of messages regarding database	migration.

DON'T PANIC!

DON'T TOUCH ANYTHING!

Aborting the operation at this point will fry your database.

At one point you will reach Nirvana: INFO: Server startup in 49318 ms (Your mileage may vary...)

Go to over to your boss and gloat over your new, functioning OC311 installation.

Now... back to work! ;)

Enjoy!

Possible messages
Some messages you might see, and what to do.

1/ If you get failure messages: DBMS Precondition failed: expected oracle, got postgresql

Don't worry... they are just info.

2/ AbandonedObjectPool is used

is also info.

3/ SLF4J: The requested version 1.5.11 by your slf4j binding is not compatible with [1.5.5, 1.5.6] SLF4J: See http://www.slf4j.org/codes.html#version_mismatch for further details.

Is more tricky. It is a very innoccous but utterly uninformative info. I lost many hours on this one (even opened a bug notice) when ultimately it amounts to nothing. SLF4J is not the problem. It warns of a version problem of this logger program, but has absolutely no effect on the loading or functioning of OC or Tomcat. So, don't loose sleep over this one, try to find the error source elsewhere.

4/ GRAVE: Error listenerStart

- OR -

GRAVE: A web application created a ThreadLocal

Well, these are REAL failure messages. Go back to the drawing board. Check the procedures, check my tutorial (I might have missed something).

And if bad comes to worse, revert your VMs to the snapshot, or recover your OC304 from the backups.