Table of Contents
This document is a list of things that may have to be considered when updating a BASE installation to a newer version. The Section 21.1, “Upgrade instructions” section only include the most recent information that is needed for updating the previous BASE version to the current version.
BASE 3.18 was the last release that supported MySQL. Since BASE 3.19 we are only testing and supporting PostgreSQL. BASE may still work with MySQL after that, but we recommend that existing installations are migrated to PostgreSQL as soon as possible.
This is the last release of BASE that is tested with MySQL 8.0. Starting with BASE 3.19 we will only test with and support PostgreSQL. BASE may still work with MySQL after that, but we recommend that existing installations are migrated to PostgreSQL as soon as possible.
Starting with this release, we no longer test BASE with MySQL versions before 8.0. We are recommending existing installations are upgraded to use MySQL 8 or migrated to PostgreSQL.
Starting with this release, Java 11 is required for running BASE.
BASE 3.15 was the last BASE version with support for Java 8.
Note that Oracle no longer provide a free JDK or JRE.
Instead, OpenJDK has to be used, which can be downloaded from
Starting with this release, we no longer test BASE with Tomcat 8 or PostgreSQL 9. Thus, we are recommening that existing installations are upgraded to at least Tomcat 9 and PostgreSQL 11.
The next BASE release, BASE 3.16, will only support Java 11 or later. BASE 3.15 is
the last BASE version that supports Java 8. Our recommendation is to upgrade to
Java 11 as soon as possible. Note that Oracle no longer provide a free JDK or JRE.
Instead, OpenJDK has to be used, which can be downloaded from
If you experience any problems with BASE 3.15 and Java 8
you could try removing the listed files from the
directory and then restart Tomcat.
We have started to test BASE with Tomcat 9 and PostgreSQL 11 and we have not found any problems so far. For new installations we recommend that Tomcat 9 and PostgreSQL 11 is used. Official support for Tomcat 8 and PostgreSQL 9 will be dropped in a future BASE version. For existing installations our recommendation is to start planning for an upgrade to Tomcat 9 and PostgreSQL 11.
The Secondary storage feature has been removed. Files that are located in the secondary storage will be marked as offline by the upgrade script. The recommendation is to replace this feature with an external files solution instead.
It is no longer possible to create new spot images or view existing spot images via the BASE web client. Existing source image files and zip archives with generated spot images have not been removed.
In the configuration directory for Tomcat there is a
file that define global options for all web applications. The settings in this file
can be overridden per web application in the
BASE 3.15 re-defines the
definition to make sure that JSP files are compiled with proper settings. Changes that
have been made to the global
web.xml file for the
<servlet> must be moved or copied to the
web.xml file for the BASE web application.
The JDBC driver to use is now found automatically based on
db.url setting in the
db.driver setting can be removed.
interface and other related code that was deprecated in BASE 3.3
has been removed. Systems that still use old authentication code
need to replace this with a newer version before updating.
The authentication system has been updated to make it easier to install more than one external authentication manager. The changes are backwards compatible and existing authentication managers should still work as before as long as they are the only ones installed. However, the existing authentication managers will probably not work well if more than one is installed since they lack some features that are neccessary in order to cooperate with other managers. Before installing more than one authentication manager it is recommended that they are updated to newer versions.
Newer authentication managers typically no longer provide support for password authentication. If the intention is that some users still should be able to login with username+password, it is recommended that the Password login form is enabled. Go to and locate the Login form customization extension point to find it.
A bug that affected the free wells information on bioplates
has been fixed. Existing bioplates may have incorrect number of
free wells and can be fixed by running a special script.
After installing the BASE 3.11.1 update, change directory to
./onetimefix.sh free_wells -u <root login> -p <root pwd>
Before BASE 3.10 a user was able to create/change/delete annotations on
an item if the user has
WRITE permission on the item and
READ permission on the annotation type.
In BASE 3.10 several changes has been made:
USE permission is required on the annotation type to be able
to create/change/delete annotations of that type. This may cause user to no
longer be able to annotate certain items, unless their permissions
are upgraded to
USE. Users with
can only read the annotation values.
A new permission level,
ANNOTATE, has been introduced.
In the permission hierarchy this sits between the
WRITE permission and can be used to give users
permissions to manage annotations but not other properties of an item.
All users with
WRITE permission automatically get
ANNOTATE permission so this change should not affect current
method for getting access to an existing session has been deprecated. A new
version has been implemented that require that an external client id
is specified. Extensions and other client application may stop working unless
they are updated. See alos Section I.5, “Application.getSessionControl()”.
It is no longer needed to run the
script as part of the upgrade or installation procedure. The funtionality
has been integrated into the regular
ServiceSessionControl API for
configuration and building Hibernate
instances has been changed due the Hibernate 5 upgrade. This change affects
extensions that use the API for storing their own data inside the BASE database.
Extensions that use this API must be updated or they will not work with BASE 3.8.
BASE will no longer run with Java 7. Unless you have already updated to Java 8 you should do so before updating to BASE 3.6. Note that BASE 3.5 works with both Java 7 and 8 so the Java update can be made ahead of time.
Tomcat 7 is no longer supported. We recommend updating to Tomcat 8 before updating to BASE 3.6. Note that BASE 3.5 works with both Tomcat 7 and 8 so the Tomcat update can be made ahead of time.
This is a major change that has caused a binary incompatibility in the BASE core API. If you depend on custom extensions or plug-ins that use the biomaterial list API this code must be updated before updating to BASE 3.5. Read more about the incompatibilities in Section I.8, “Biomaterial lists has been replaced with item lists”.
Oracle is no longer supporting Java 1.7. We are recommending Java 8 for running BASE. Java 7 is still supported, but will be removed in the next version (BASE 3.6).
We have now tested BASE with Tomcat 8 and it seems to work without any problems. Support for Tomcat 7 will be removed in the next version (BASE 3.6).
If you are still running an BASE 2.17 (or earlier) BASE version and want to update to BASE 3.4 you must first update to BASE 3.3 or earlier.
As announced earlier web services support has been removed in BASE 3.4. If anyone require web services support or similar we recommend using the BASE extensions mechanism to implement exactly what is needed for that project and we also beleive that a simplier API such as JSON is preferable.
base.config there is a
setting. Servers running with PostgreSQL as the database should change the
A bug that affected remaining quantity calculations for
biomaterial item has been fixed. Existing items may have been
saved with incorrect remaining quantity and must be fixed.
After installing the BASE 3.3.3 update, the existing
remaining quantity values are fix by running a special script.
Change directory to
./onetimefix.sh remaining_quantity -u <root login> -p <root pwd>
BASE now require Java SE 7. Servers with Java SE 6 or older should be updated to Java SE 7 before installing BASE 3.3.
BASE now require Tomcat 7. Servers with Tomcat 6 or older should be updated to Tomcat 7 before installing BASE 3.3.
The current implementation is most likely not very useful and has limited support for accessing information in BASE. Therefore it has been decided to remove the web services support in BASE 3.4. If anyone require web services support or similar we recommend using the BASE extensions mechanism to implement exactly what is needed for that project and we also beleive that a simplier API such as JSON is preferable.
The plug-in functionality for custom logging has been converted to an extension point. The default database logging will continue to function, but custom logging implementations must be converted to an extension. See Section I.11, “BASE 3.2 release” and Section 27.8.10, “Logging managers” for more information.
|Upgrading to BASE 3 is possible 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 is possible. Also note that since BASE 3.3 we no longer actively test the upgrade script. If upgrading doesn't work for a particular BASE 3.x version (where x > 2) please try to upgrade to BASE 3.2 first and then from BASE 3.2 to BASE 3.x.
|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.
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 22.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 22.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.
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.
|The deprecated importers can be re-enabled by an administrator from thepage, but they are lacking features that are available in the new importers so this is not something that we recommend.|
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.
We only support updating to BASE 3 from BASE 2.17. If you have an older BASE version and wish to update to BASE 3, you first have to upgrade to BASE 2.17. BASE 2.17 can be downloaded from the BASE download page. Documentation for BASE 2.17 is available as part of the download and at https://base.thep.lu.se/chrome/site/2.17/html/index.html.