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

Last change on this file since 7545 was 7545, checked in by Nicklas Nordborg, 3 years ago

References #2131: Add support for installing multiple authentication managers

Added note to the update information about the changes.

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