source: trunk/doc/src/docbook/appendix/update_warnings.xml @ 7826

Last change on this file since 7826 was 7826, checked in by Nicklas Nordborg, 20 months ago

References #2214: Upgrade Hibernate and other 3-rd party components

Added a note about testing is only made with MySQL to the update section.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 22.1 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE appendix PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: update_warnings.xml 7826 2020-06-09 11:43:11Z nicklas $
7 
8  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 3
16  of the License, or (at your option) any later version.
17 
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<appendix id="appendix.update_warnings">
28  <?dbhtml filename="updatewarnings.html" ?>
29  <title>Things to consider when updating an existing BASE installation</title>
30  <para>
31    This document is a list of things that may have to be considered
32    when updating a BASE installation to a newer version. The <xref 
33    linkend="installation.upgrade" /> section only include the most
34    recent information that is needed for updating the previous BASE version
35    to the current version.
36  </para>
37
38  <sect1 id="appendix.update_warnings.3.17">
39    <title>BASE 3.17</title>
40 
41    <bridgehead>MySQL versions before 8.0 are no longer supported</bridgehead>
42    <para>
43      Starting with this release, we no longer test BASE with MySQL versions
44      before 8.0. We are recommending existing installations are upgraded to
45      use MySQL 8 or migrated to PostgreSQL.
46    </para>
47   
48  </sect1>
49
50 
51  <sect1 id="appendix.update_warnings.3.16">
52    <title>BASE 3.16</title>
53 
54    <bridgehead>Java 11 or later is now required (OpenJDK)</bridgehead>
55    <para>
56      Starting with this release, Java 11 is required for running BASE.
57      BASE 3.15 was the last BASE version with support for Java 8.
58      Note that Oracle no longer provide a free JDK or JRE.
59      Instead, OpenJDK has to be used, which can be downloaded from
60      <ulink url="https://openjdk.java.net/" />
61    </para>
62   
63    <bridgehead>Tomcat 8 and PostgreSQL 9 are no longer supported</bridgehead>
64    <para>
65      Starting with this release, we no longer test BASE with Tomcat 8
66      or PostgreSQL 9. Thus, we are recommening that existing installations
67      are upgraded to at least Tomcat 9 and PostgreSQL 11.
68    </para>
69   
70  </sect1>
71 
72  <sect1 id="appendix.update_warnings.3.15">
73    <title>BASE 3.15</title>
74 
75    <bridgehead>Consider upgrading to Java 11 (OpenJDK)</bridgehead>
76    <para>
77      The next BASE release, BASE 3.16, will only support Java 11 or later. BASE 3.15 is
78      the last BASE version that supports Java 8. Our recommendation is to upgrade to
79      Java 11 as soon as possible. Note that Oracle no longer provide a free JDK or JRE.
80      Instead, OpenJDK has to be used, which can be downloaded from
81      <ulink url="https://openjdk.java.net/" />
82    </para>
83   
84    <para>
85      If you experience any problems with BASE 3.15 and Java 8
86      you could try removing the listed files from the <filename>www/WEB-INF/lib</filename>
87      directory and then restart Tomcat.
88    </para>
89   
90    <itemizedlist>
91      <listitem><filename>java.activation-api-1.2.0.jar</filename></listitem>
92      <listitem><filename>jaxb-api-2.3.1.jar</filename></listitem>
93      <listitem><filename>jaxb-core-2.3.0.1.jar</filename></listitem>
94      <listitem><filename>jaxb-impl-2.3.1.jar</filename></listitem>
95    </itemizedlist>
96 
97    <bridgehead>Consider upgrading to Tomcat 9 and PostgreSQL 11</bridgehead>
98    <para>
99      We have started to test BASE with Tomcat 9 and PostgreSQL 11 and we have
100      not found any problems  so far. For new installations we recommend that Tomcat 9
101      and PostgreSQL 11 is used. Official support for Tomcat 8 and PostgreSQL 9 will be
102      dropped in a future BASE version. For existing installations our recommendation
103      is to start planning for an upgrade to Tomcat 9 and PostgreSQL 11.
104    </para>
105 
106    <bridgehead>Secondary storage support has been removed</bridgehead>
107    <para>
108      The <guilabel>Secondary storage</guilabel> feature has been removed.
109      Files that are located in the secondary storage will be marked as offline
110      by the upgrade script. The recommendation is to replace this feature with
111      an external files solution instead.
112    </para>
113   
114    <bridgehead>Spot images support has been removed</bridgehead>
115    <para>
116      It is no longer possible to create new spot images or view existing
117      spot images via the BASE web client. Existing source image files and
118      zip archives with generated spot images have not been removed.
119    </para>
120 
121    <bridgehead>Customizations made in Tomcat's global web.xml file</bridgehead>
122    <para>
123      In the configuration directory for Tomcat there is a <filename>web.xml</filename>
124      file that define global options for all web applications. The settings in this file
125      can be overridden per web application in the <filename>WEB-INF/classes/web.xml</filename>.
126      BASE 3.15 re-defines the <code>jsp</code> <sgmltag class="starttag">servlet</sgmltag>
127      definition to make sure that JSP files are compiled with proper settings. Changes that
128      have been made to the global <filename>web.xml</filename> file for the <code>jsp</code>
129      <sgmltag class="starttag">servlet</sgmltag> must be moved or copied to the
130      <filename>web.xml</filename> file for the BASE web application.
131    </para>
132 
133  </sect1>
134 
135  <sect1 id="appendix.update_warnings.3.14">
136    <title>BASE 3.14</title>
137 
138    <bridgehead>The db.driver setting is no longer used</bridgehead>
139    <para>
140      The JDBC driver to use is now found automatically based on
141      the <constant>db.url</constant> setting in the <filename>base.config</filename>
142      file. The <constant>db.driver</constant> setting can be removed.
143    </para>
144   
145    <bridgehead>The (very) old Authenticator API has been removed</bridgehead>
146    <para>
147      The <code>net.sf.basedb.core.authentication.Authenticator</code>
148      interface and other related code that was deprecated in BASE 3.3
149      has been removed. Systems that still use old authentication code
150      need to replace this with a newer version before updating.
151    </para>
152
153    <bridgehead>Changes to the authentication system</bridgehead>
154    <para>
155      The authentication system has been updated to make it easier to
156      install more than one external authentication manager. The changes
157      are backwards compatible and existing authentication managers should
158      still work as before as long as they are the only ones installed.
159      However, the existing authentication managers will probably not work
160      well if more than one is installed since they lack some features that
161      are neccessary in order to cooperate with other managers. Before installing
162      more than one authentication manager it is recommended that they are
163      updated to newer versions.
164    </para>
165   
166    <para>
167      Newer authentication managers typically no longer provide support for
168      password authentication. If the intention is that some users still should be
169      able to login with username+password, it is recommended that the
170      <guilabel>Password login form</guilabel> is enabled. Go to
171      <menuchoice>
172        <guimenu>Administrate</guimenu>
173        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
174        <guimenuitem>Overview</guimenuitem>
175      </menuchoice> and locate the <guilabel>Login form customization</guilabel>
176      extension point to find it.
177    </para>
178   
179  </sect1>
180 
181  <sect1 id="appendix.update_warnings.3.11.1">
182    <title>BASE 3.11.1</title>
183 
184    <bridgehead>Free wells on bioplates</bridgehead>
185    <para>
186      A bug that affected the free wells information on bioplates
187      has been fixed. Existing bioplates may have incorrect number of
188      free wells and can be fixed by running a special script.
189     
190      After installing the BASE 3.11.1 update, change directory to
191      <filename class="directory">&lt;base-dir&gt;/bin/</filename> 
192      and issue
193<programlisting>
194./onetimefix.sh free_wells -u &lt;root login&gt; -p &lt;root pwd&gt;
195</programlisting>
196    </para>
197   
198  </sect1>
199 
200  <sect1 id="appendix.update_warnings.3.10">
201    <title>BASE 3.10</title>
202 
203    <bridgehead>Changed permissions for annotating items</bridgehead>
204    <para>
205      Before BASE 3.10 a user was able to create/change/delete annotations on
206      an item if the user has <code>WRITE</code> permission on the item and
207      <code>READ</code> permission on the  annotation type.
208      In BASE 3.10 several changes has been made:
209    </para>
210   
211    <itemizedlist>
212      <listitem>
213        <para>
214          <code>USE</code> permission is required on the annotation type to be able
215          to create/change/delete annotations of that type. This may cause user to no
216          longer be able to annotate certain items, unless their permissions
217          are upgraded to <code>USE</code>. Users with <code>READ</code> permission
218          can only read the annotation values.
219        </para>
220      </listitem>
221     
222      <listitem>
223        <para>
224          A new permission level, <code>ANNOTATE</code>, has been introduced.
225          In the permission hierarchy this sits between the <code>READ</code> 
226          and <code>WRITE</code> permission and can be used to give users
227          permissions to manage annotations but not other properties of an item.
228          All users with <code>WRITE</code> permission automatically get
229          <code>ANNOTATE</code> permission so this change should not affect current
230          users.
231        </para>
232      </listitem>
233    </itemizedlist>
234 
235  </sect1>
236 
237 
238  <sect1 id="appendix.update_warnings.3.9">
239    <title>BASE 3.9</title>
240 
241    <bridgehead>Incompatible API change Application API</bridgehead>
242    <para>
243      The <classname docapi="net.sf.basedb.core">Application.getSessionControl()</classname> 
244      method for getting access to an existing session has been deprecated. A new
245      version has been implemented that require that an <emphasis>external client id</emphasis>
246      is specified. Extensions and other client application may stop working unless
247      they are updated. See alos <xref linkend="appendix.incompatible.session-control"/>.
248    </para>
249 
250  </sect1>
251 
252 
253  <sect1 id="appendix.update_warnings.3.8">
254    <title>BASE 3.8</title>
255 
256    <bridgehead>updateindexes.sh is no longer needed</bridgehead>
257    <para>
258      It is no longer needed to run the <filename>updateindexes.sh</filename>
259      script as part of the upgrade or installation procedure. The funtionality
260      has been integrated into the regular <filename>updatedb.sh/initdb.sh</filename>
261      scripts.
262    </para>
263   
264    <bridgehead>Incompatible API change in ServiceSessionControl</bridgehead>
265    <para>
266      The <classname docapi="net.sf.basedb.core">ServiceSessionControl</classname> API for
267      configuration and building Hibernate <classname>SessionFactory</classname>
268      instances has been changed due the Hibernate 5 upgrade. This change affects
269      extensions that use the API for storing their own data inside the BASE database.
270      Extensions that use this API must be updated or they will not work with BASE 3.8.
271    </para>
272 
273  </sect1>
274 
275  <sect1 id="appendix.update_warnings.3.6">
276    <title>BASE 3.6</title>
277 
278    <bridgehead>Update to Java 8</bridgehead>
279    <para>
280      BASE will no longer run with Java 7. Unless you have already
281      updated to Java 8 you should do so before updating to BASE 3.6.
282      Note that BASE 3.5 works with both Java 7 and 8 so the Java
283      update can be made ahead of time.
284    </para>
285   
286    <bridgehead>Update to Tomcat 8</bridgehead>
287    <para>
288      Tomcat 7 is no longer supported. We recommend updating
289      to Tomcat 8 before updating to BASE 3.6. Note that
290      BASE 3.5 works with both Tomcat 7 and 8 so the Tomcat
291      update can be made ahead of time.
292    </para>
293 
294  </sect1>
295 
296  <sect1 id="appendix.update_warnings.3.5">
297    <title>BASE 3.5</title>
298
299    <bridgehead>Biomaterial lists have been replaced with item lists</bridgehead>
300    <para>
301      This is a major change that has caused a binary incompatibility in the BASE core
302      API. If you depend on custom extensions or plug-ins that use the biomaterial list
303      API this code must be updated before updating to BASE 3.5. Read more
304      about the incompatibilities in <xref linkend="appendix.incompatible.itemlists" />.
305    </para>
306   
307    <bridgehead>Consider updating to Java 8</bridgehead>
308    <para>
309      Oracle is no longer supporting Java 1.7. We are recommending Java 8
310      for running BASE. Java 7 is still supported, but will be removed
311      in the next version (BASE 3.6).
312    </para>
313   
314    <bridgehead>Consider updating to Tomcat 8</bridgehead>
315    <para>
316      We have now tested BASE with Tomcat 8 and it seems to work without
317      any problems. Support for Tomcat 7 will be removed in the next
318      version (BASE 3.6).
319    </para>
320   
321  </sect1>
322 
323  <sect1 id="appendix.update_warnings.3.4">
324    <title>BASE 3.4</title>
325   
326    <bridgehead>Updating from BASE 2.17 is no longer possible</bridgehead>
327    <para>
328      If you are still running an BASE 2.17 (or earlier) BASE version
329      and want to update to BASE 3.4 you must first update to BASE 3.3
330      or earlier.
331    </para>
332   
333    <bridgehead>Web services support has been removed</bridgehead>
334    <para>
335      As announced earlier web services support has been removed in BASE 3.4.
336      If anyone require web services support or similar we recommend using the BASE
337      extensions mechanism to implement exactly what is needed for that project and
338      we also beleive that a simplier API such as JSON is preferable.
339    </para>
340   
341    <bridgehead>PostgreSQL users should change db.dialect</bridgehead>
342    <para>
343      In <filename>base.config</filename> there is a <constant>db.config</constant>
344      setting. Servers running with PostgreSQL as the database should change the
345      dialect to <classname>org.hibernate.dialect.PostgreSQL9Dialect</classname>
346      since the <classname>org.hibernate.dialect.PostgreSQLDialect</classname> has
347      been deprecated.
348    </para>
349   
350  </sect1>
351
352  <sect1 id="appendix.update_warnings.3.3.3">
353    <title>BASE 3.3.3</title>
354 
355    <bridgehead>Remaining quantity</bridgehead>
356    <para>
357      A bug that affected remaining quantity calculations for
358      biomaterial item has been fixed. Existing items may have been
359      saved with incorrect remaining quantity and must be fixed.
360      After installing the BASE 3.3.3 update, the existing
361      remaining quantity values are fix by running a special script.
362      Change directory to <filename class="directory">&lt;base-dir&gt;/bin/</filename> 
363      and issue
364<programlisting>
365./onetimefix.sh remaining_quantity -u &lt;root login&gt; -p &lt;root pwd&gt;
366</programlisting>
367    </para>
368   
369  </sect1>
370 
371  <sect1 id="appendix.update_warnings.3.3">
372    <title>BASE 3.3</title>
373
374    <bridgehead>Content security policy</bridgehead>
375    <para>
376      The BASE web client now set a rather strict <emphasis>Content
377      Security Policy</emphasis> that prevent browsers from executing
378      code (including JavaScript) that is considered unsafe. Some extensions
379      may cease to work due to this. Go to
380      <menuchoice>
381        <guimenu>Administrate</guimenu>
382        <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
383        <guimenuitem>Overview</guimenuitem>
384      </menuchoice> 
385      (after upgrading) to see if there are any warnings about this.
386      Read more in <xref linkend="appendix.web.xml.csp-filter" />
387      for information about how to relax the policy.
388    </para>
389
390    <bridgehead>Java SE 7 is required</bridgehead>
391    <para>
392      BASE now require <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java SE 7</ulink>.
393      Servers with Java SE 6 or older should be updated to Java SE 7 before installing BASE 3.3.
394    </para>
395
396    <bridgehead>Tomcat 7 is required</bridgehead>
397    <para>
398      BASE now require <ulink url="http://tomcat.apache.org/download-70.cgi">Tomcat 7</ulink>.
399      Servers with Tomcat 6 or older should be updated to Tomcat 7 before installing BASE 3.3.
400    </para>
401   
402    <bridgehead>Web services support has been deprecated</bridgehead>
403    <para>
404      The current implementation is most likely not very useful and has limited
405      support for accessing information in BASE. Therefore it has been decided to
406      remove the web services support in BASE 3.4. If anyone require web services
407      support or similar we recommend using the BASE extensions mechanism to implement
408      exactly what is needed for that project and we also beleive that a simplier
409      API such as JSON is preferable.
410    </para>
411
412  </sect1>
413 
414  <sect1 id="appendix.update_warnings.3.2">
415    <title>BASE 3.2</title>
416 
417    <bridgehead>Custom logging implementations must be updated</bridgehead>
418    <para>
419      The plug-in functionality for custom logging has been converted
420      to an extension point. The default database logging will continue
421      to function, but custom logging implementations must be converted
422      to an extension. See <xref linkend="appendix.incompatible.3.2" /> and
423      <xref linkend="extensions_developer.logging" /> for more information.
424    </para>
425 
426  </sect1>
427 
428  <sect1 id="appendix.update_warnings.3.0">
429    <title>BASE 3.0</title>
430   
431    <note>
432      <title>Upgrading to BASE 3 is possible from BASE 2.17 only</title>
433      <para>
434        If your BASE is an older 2.x version you'll need to upgrade
435        to BASE 2.17 before an upgrade to BASE 3 is possible. Also note
436        that since BASE 3.3 we no longer actively test the upgrade
437        script. If upgrading doesn't work for a particular BASE 3.x version
438        (where x &gt; 2) please try to upgrade to BASE 3.2 first and then
439        from BASE 3.2 to BASE 3.x.
440      </para>
441    </note>
442
443    <warning>
444      <title>Make sure that you have a recent backup of the BASE 2.17 database</title>
445      <para>
446        Before starting the upgrade from BASE 2.17 to BASE 3 ensure that you
447        have a recent backup. If the upgrade fails you must restore the
448        2.17 database before you can try again. The upgrade only changes the
449        'static' part of the database, so you do not have to restore the
450        'dynamic' part or the uploaded files.
451      </para>
452    </warning>
453
454    <bridgehead>Old plug-ins and extensions may not work</bridgehead>
455    <para>
456      The BASE API has changed in several places and it is not certain that
457      plug-ins and extensions developed for BASE 2 works with BASE 3. The
458      upgrade will disable all plug-ins and extensions that are currently installed.
459      Before you upgrade we recommend that you go through all (external) plug-ins
460      and check if there is an updated version. The recommended approach
461      is to first upgrade BASE and then install updated versions of plug-ins
462      and extensions following the instructions in <xref 
463      linkend="plugins.installation"/>.
464    </para>
465   
466    <para>
467      If there is no updated version of a specific plug-in you may try
468      a manual re-installation of the old plug-ins. Follow the instructions
469      in <xref linkend="plugins.installation.manual" />.
470    </para>
471   
472    <para>
473      If there is no updated version and the old plug-in doesn't work with
474      BASE 3, you'll need to decide if you really need the plug-in or if
475      the upgrade should wait until a new version of the plug-in
476      has been released.
477    </para>
478   
479    <bridgehead>Batch item importer changes</bridgehead>
480    <para>
481      There are several changes to batch item importers that may affect
482      current workflows and file templates used for importing data.
483    </para>
484   
485    <itemizedlist>
486      <listitem>
487        <para>
488          Sample and extract importers: The 'pooled' column is no longer used.
489          Instead a 'parent type' column should be used with
490          the parent type as a string value (BIOSOURCE, SAMPLE or EXTRACT).
491          Existing importer configurations and file templates may have to be
492          updated. If no parent type is specified the sample importer assumes
493          a biosource and the extract importer assumes a sample.
494        </para>
495      </listitem>
496      <listitem>
497        <para>
498          Labeled extract importer: This has been deprecated and it is recommended
499          that the <emphasis>Extract importer</emphasis> is used instead.
500          We recommend that existing labeled extract importer configurations are re-created as extract
501          importer configurations. The old labeled extract importer can be
502          re-enabled, but note that the existing configurations still need
503          to be changed due to the 'pooled' column is no longer used.
504        </para>
505      </listitem>
506      <listitem>
507        <para>
508          Hybridization importer: This has been deprecated and we recommend
509          that the <emphasis>Physical bioassay importer</emphasis> is used instead.
510          Existing hybridization importer configurations should be re-created as
511          physical bioassay importer configurations.
512        </para>
513      </listitem>
514      <listitem>
515        <para>
516          Scan importer: This has been deprecated and it is recommended
517          that the <emphasis>Derived bioassay importer</emphasis> is used instead.
518          Existing scan importer configurations should be re-created as derived
519          bioassay importer configurations.
520        </para>
521      </listitem>
522    </itemizedlist>
523   
524    <note>
525      The deprecated importers can be re-enabled by an administrator from the
526      <menuchoice>
527        <guimenu>Administrate</guimenu>
528        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
529        <guimenuitem>Overview</guimenuitem>
530      </menuchoice> page, but they are
531      lacking features that are available in the new importers so this is not
532      something that we recommend.
533    </note>
534   
535    <bridgehead>MySQL and PostgreSQL versions</bridgehead>
536    <para>
537      We have only tested BASE 3 with PostgreSQL 9.1. If anyone
538      experiences any issues with earlier PostgreSQL versions, we
539      recommend an upgrade to PostgreSQL 9.1. This is a change since
540      BASE 2 which was tested with PostgreSQL 8.4. Even though BASE 3
541      may work with older PostgreSQL versions, we don't have the resources
542      needed to test and provide support for it.
543    </para>
544   
545    <para>
546      We have only tested BASE 3 with MySQL 5.1 (no change since BASE 2).
547      If anyone experiences any issues with earlier (or later) MySQL versions,
548      we recommend an upgrade/downgrade to MySQL 5.1.
549    </para>
550 
551  </sect1>
552 
553  <sect1 id="appendix.update_warnings.2.x">
554    <title>All BASE 2.x releases</title>
555   
556    <para>
557      We only support updating to BASE 3 from BASE 2.17. If you have an older BASE
558      version and wish to update to BASE 3, you first have to upgrade to BASE 2.17.
559      BASE 2.17 can be downloaded from the <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
560      download page</ulink>. Documentation for BASE 2.17 is available as part of the
561      download and at <ulink url="http://base.thep.lu.se/chrome/site/2.17/html/index.html"
562      >http://base.thep.lu.se/chrome/site/2.17/html/index.html</ulink>.
563    </para>
564
565  </sect1>
566 
567</appendix>
568
Note: See TracBrowser for help on using the repository browser.