20.1. Upgrade instructions

[Important] Important information for upgrading from BASE 2.17 to BASE 3.0

Upgrading is supported from BASE 2.17 only

If your BASE is an older 2.x version you'll need to upgrade to BASE 2.17 before an upgrade to BASE 3.0 is possible.

[Warning] Make sure that you have a recent backup of the BASE 2.17 database

Before starting the upgrade from BASE 2.17 to BASE 3 ensure that you have a recent backup. If the upgrade fails you must restore the 2.17 database before you can try again. The upgrade only changes the 'static' part of the database, so you do not have to restore the 'dynamic' part or the uploaded files.

Old plug-ins and extensions may not work

The BASE API has changed in several places and it is not certain that plug-ins and extensions developed for BASE 2 works with BASE 3. The upgrade will disable all plug-ins and extensions that are currently installed. Before you upgrade we recommend that you go through all (external) plug-ins and check if there is an updated version. The recommended approach is to first upgrade BASE and then install updated versions of plug-ins and extensions following the instructions in Section 21.1, “Managing plug-ins and extensions”.

If there is no updated version of a specific plug-in you may try a manual re-installation of the old plug-ins. Follow the instructions in Section 21.1.2, “Manual plug-in registration”.

If there is no updated version and the old plug-in doesn't work with BASE 3, you'll need to decide if you really need the plug-in or if the upgrade should wait until a new version of the plug-in has been released.

Batch item importer changes

There are several changes to batch item importers that may affect current workflows and file templates used for importing data.

  • Sample and extract importers: The 'pooled' column is no longer used. Instead a 'parent type' column should be used with the parent type as a string value (BIOSOURCE, SAMPLE or EXTRACT). Existing importer configurations and file templates may have to be updated. If no parent type is specified the sample importer assumes a biosource and the extract importer assumes a sample.

  • Labeled extract importer: This has been deprecated and it is recommended that the Extract importer is used instead. We recommend that existing labeled extract importer configurations are re-created as extract importer configurations. The old labeled extract importer can be re-enabled, but note that the existing configurations still need to be changed due to the 'pooled' column is no longer used.

  • Hybridization importer: This has been deprecated and we recommend that the Physical bioassay importer is used instead. Existing hybridization importer configurations should be re-created as physical bioassay importer configurations.

  • Scan importer: This has been deprecated and it is recommended that the Derived bioassay importer is used instead. Existing scan importer configurations should be re-created as derived bioassay importer configurations.

[Note] Note
The deprecated importers can be re-enabled by an administrator from the AdministratePlug-ins & extensionsOverview page, but they are lacking features that are available in the new importers so this is not something that we recommend.

MySQL and PostgreSQL versions

We have only tested BASE 3 with PostgreSQL 9.1. If anyone experiences any issues with earlier PostgreSQL versions, we recommend an upgrade to PostgreSQL 9.1. This is a change since BASE 2 which was tested with PostgreSQL 8.4. Even though BASE 3 may work with older PostgreSQL versions, we don't have the resources needed to test and provide support for it.

We have only tested BASE 3 with MySQL 5.1 (no change since BASE 2). If anyone experiences any issues with earlier (or later) MySQL versions, we recommend an upgrade/downgrade to MySQL 5.1.

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

[Tip] Notify logged in users!

If there are users logged in to your BASE server, it may be nice of you to notify them a few minutes prior to shutting down the BASE server. See Section 20.4.1, “Sending a broadcast message to logged in users”.

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 3.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 http://base.thep.lu.se/wiki/BuildingBase 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.

Start Tomcat

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

Done! Upgrade of BASE is finished.