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

Last change on this file since 7916 was 7916, checked in by Nicklas Nordborg, 11 months ago

Fixes #2244: Add notice about support for MySQL is ending

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