OpenClinica User Manual/Ubuntu10Upgrade

Upgrading OpenClinica 3.0.4.x to 3.1.x on Ubuntu

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

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

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

# BACKUP THE DB
pg_dump openclinica  > ./BACKUP/OC30-db-`date +%b-%d-%Y`.sql 
# Adjust to your needs. If your database is remote, log into the 
# 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:

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

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

Installing the new version of the .war

# Now, the fun part...
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 
# If you have a previous installation, you should copy the content of 
# your openclinica.data folder in /usr/share/tomcat6/openclinica.data
sudo cp -Rp ./oc/BACKUP/openclinica.data/* /usr/share/tomcat6/openclinica.data
sudo chown tomcat6.  /usr/share/tomcat6/openclinica.data

PostgreSQL actions

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

sudo apt-get -y install postgresql postgresql-client

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

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

Editing datainfo.properties

# BACK IN THE OpenClinica Machine
# Configuration file:
# ../OpenClinica/WEB-INF/classes/datainfo.properties

Insert the details of your configuration. Pay special attention to:

1/ Database password: in this example, passwd_postgresql

2/ Database location: defaults to <localhost>, 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

# Edit setenv.sh with your favourite vim ;) 
sudo vim setenv.sh

I changed mine to:

export JAVA_OPTS="-Xms256m -Xmx512m -XX:MaxPermSize=256m"

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.