21.1. Upgrade instructions

21.1. Upgrade instructions
Prev	Chapter 21. Installation, setup, migration, and upgrade instructions	Next

Important information for upgrading to the current release

	Important information for upgrading to the current release
This section list some important information that may or may not apply when upgrading from the previous BASE release to the current release (eg. 2.8.x to 2.9.x). If you are upgrading from a BASE installation that is older (eg. 2.7.x to 2.9.x) you should also read Appendix L, Things to consider when updating an existing BASE installation. BASE 2.9 must use a database that supports UTF-8 If you are upgrading from BASE 2.8 or lower and your existing database is not using UTF-8 you must convert the database to UTF-8 before you execute the `./updatedb.sh` script. BASE 2.9 includes a utility that can convert an existing MySQL database. After installing the BASE 2.9 files, but before running the `./updatedb.sh` script, execute the following on the command line: cd <base-dir>/bin ./onetimefix.sh utf8 -x The `-x` option makes the script update the database immediately. You can leave this option out to have it generate a SQL script file (`convert-to-utf8.sql`) instead. The script will by default not try to convert tables that it already thinks are using UTF-8. If the script for some reason is incorrect when detecting this, you can use the option `-f` to force conversion of all tables. The conversion utility only works with MySQL. PostgreSQL users should instead use a backup and restore using as described in the PostgreSQL manual. Eg. dump the existing BASE database, create a new database that uses UTF8 and restore the backup into the new database.

This section list some important information that may or may not apply when upgrading from the previous BASE release to the current release (eg. 2.8.x to 2.9.x). If you are upgrading from a BASE installation that is older (eg. 2.7.x to 2.9.x) you should also read Appendix L, Things to consider when updating an existing BASE installation.

BASE 2.9 must use a database that supports UTF-8

If you are upgrading from BASE 2.8 or lower and your existing database is not using UTF-8 you must convert the database to UTF-8 before you execute the ./updatedb.sh script.

BASE 2.9 includes a utility that can convert an existing MySQL database. After installing the BASE 2.9 files, but before running the ./updatedb.sh script, execute the following on the command line:


cd <base-dir>/bin
./onetimefix.sh utf8 -x

The -x option makes the script update the database immediately. You can leave this option out to have it generate a SQL script file (convert-to-utf8.sql) instead. The script will by default not try to convert tables that it already thinks are using UTF-8. If the script for some reason is incorrect when detecting this, you can use the option -f to force conversion of all tables.

The conversion utility only works with MySQL. PostgreSQL users should instead use a backup and restore using as described in the PostgreSQL manual. Eg. dump the existing BASE database, create a new database that uses UTF8 and restore the backup into the new database.

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

	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 21.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 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.