21.1. Upgrade instructions

[Important] Bug in the LOWESS plug-in affecting BASE version 2.0 -- 2.7.1

BASE 2.7.2 fixes a serious bug in the LOWESS plug-in shipped as a part of the BASE package. The bug is found in all BASE versions between 2.0 and 2.7.1, and has caused incorrect normalization values to be calculated. All data that has been normalized with the LOWESS plug-in prior to BASE 2.7.2 should be considered invalid and needs to be re-normalized with the fixed version. Downstream analysis steps that has used the incorrectly normalized data also needs to be redone. For more information about the bug see http://base.thep.lu.se/ticket/1077

BASE 2.7.2 includes a utility for finding all experiments/bioassay sets that includes data normalized with the LOWESS plug-in. An administrator can use this utility to extract a list of all experiments/bioassay sets that needs to be fixed. The utility can also tag the name of the found experiments/bioassay sets with FIX LOWESS to make it easier to find data that needs to be fixed.

The utility can't see any difference between data normalized with the old version and the fixed version. It will simply report all data that has been normalized with the LOWESS plug-in. Only use the utility a single time right after the upgrade to BASE 2.7.2.

The utility is a command line program that should be executed on the BASE application (web) server.


cd <base-dir>/bin
./onetimefix.sh lowess_warn -u <login> -p <password> -f

We recommend running the utility as the root user. The -f option is optional. If it is included the found experiments/bioassay sets are tagged with FIX LOWESS, otherwise only a list with the information is generated.

[Important] BASE 2.7 requires Tomcat 6 or higher

If you are upgrading from older BASE versions to BASE 2.7 or higher you must also make sure that you are running Tomcat 6 or higher. Earlier BASE versions only required Tomcat 5.5. If you are not already running Tomcat 6 you need to upgrade. Other servlet engines may work if they implement the Servlet 2.5 and JSP 2.1 specifications.

[Important] Upgrading from BASE 2.4.3 or lower to 2.4.4 or higher

Older releases of BASE 2 used to create indexes for many columns in the dynamic database. The same columns are part of the primary key for the tables so the indexes are not really needed. The result is very bad performance since the database engine sometimes get stuck in "index update" mode making the entire server very slow. BASE 2.4.4 no longer creates the indexes. Indexes on existing tables should be dropped to increase the performance. Tests have shown a 50-90% decrease in execution time for some plug-ins (http://base.thep.lu.se/ticket/294).

Removing the indexes is very simple. After the server has been upgraded following the usual instructions below, issue the the following commands:

cd <basedir>/bin
./dynamicdb.sh -v -dropindexes

Skip the -dropindexes option to do a dry run without actually deleting the indexes.

As always, backup your database before attempting an upgrade. The BASE team performs extensive testing before releasing a new version of BASE but there are always a possibility for unexpected events during upgrades. In upgrades requiring a change in the underlying database there is no (supported) way to revert to a previous version of BASE using BASE tools, you need to use your backup for this use case.

The strategy here is to install the new BASE release to another directory than the one in use. This requires transfer of configuration settings to the new install but more on that below.

Shut down the Tomcat server

If the BASE application is not shut down already, it is time to do it now. Do something like sudo /etc/init.d/tomcat6.0 stop

Rename your current server

Rename your current BASE installation mv /path/to/base /path/to/base_old.

Download and unpack BASE

There are several ways to download BASE. Please refer to section Section 4.1.1, “Download” for information on downloading BASE, and select the item matching your download option:

Pre-compiled package

If you selected to download a pre-compiled package, unpack the downloaded file with tar zxpf base-...tar.gz.

Source package

If you selected to download a source package, unpack the downloaded file with tar zxpf base-...src.tar.gz. Change to the new directory, and issue ant package.bin. This will create a binary package in the current directory. Unpack this new package (outside of the source file hierarchy).

Subversion checkout

This option is for advanced users only and is not covered here. Please refer to Section 31.2, “Subversion / building BASE” for information on this download option.

Transfer files and settings

Settings from the previous installation must be transferred to the new installation. This is most easily done by comparing the configuration files from the previous install with the new files. Do not just copy the old files to the new install since new options may have appeared.

In the main BASE configuration file, <base-dir>/www/WEB-INF/classes/base.config, fields that needs to be transferred are usually db.username, db.password, and userfiles.

Local settings in the raw data tables, <base-dir>/www/WEB-INF/classes/raw-data-types.xml, may need to be transferred. This also includes all files in the <base-dir>/www/WEB-INF/classes/raw-data-types and <base-dir>/www/WEB-INF/classes/extended-properties directories.

Updating database schema

It is recommended that you also perform an update of your database schema. Running the update scripts are not always necessary when upgrading BASE, but the running the update scripts are safe even in cases when there is no need to run them. Change directory to <base-dir>/bin/ and issue

sh ./updatedb.sh [base_root_login] base_root_password
sh ./updateindexes.sh

where base_root_login is the login for the root user and base_root_password is the password. The login is optional. If not specified, root is used as the login.

Remove Tomcat cache

As Tomcat user, remove cached files and directories. Do something like

cd /usr/share/apache-tomcat-6.0/
rm -rf work/Catalina

Start Tomcat

Start the Tomcat server: sudo /etc/init.d/tomcat6.0 start

Done! Upgrade of BASE is finished.