# 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

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:

### Editing 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:
I changed mine to:
$^†$ 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...)
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:
(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.