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

Last change on this file since 6862 was 6862, checked in by Nicklas Nordborg, 7 years ago

References #1926: Switch to Java 8

Updated installation documentation.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 12.4 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 6862 2015-04-15 11:01:57Z 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.6">
39    <title>BASE 3.6</title>
40 
41    <bridgehead>Update to Java 8</bridgehead>
42    <para>
43      BASE will no longer run with Java 7. Unless you have already
44      updated to Java 8 you should do so before updating to BASE 3.6.
45      Note that BASE 3.5 also works with both Java 7 and 8 so the Java
46      update can be made ahead of time.
47    </para>
48 
49  </sect1>
50 
51  <sect1 id="appendix.update_warnings.3.5">
52    <title>BASE 3.5</title>
53
54    <bridgehead>Biomaterial lists have been replaced with item lists</bridgehead>
55    <para>
56      This is a major change that has caused a binary compatibility in the BASE core
57      API. If you depend on custom extensions or plug-ins that use the biomaterial list
58      API this code must be updated before updating to BASE 3.5. Read more
59      about the incompatibilities in <xref linkend="appendix.incompatible.itemlists" />.
60    </para>
61   
62    <bridgehead>Consider updating to Java 8</bridgehead>
63    <para>
64      Oracle is no longer supporting Java 1.7. We are recommending Java 8
65      for running BASE. Java 7 is still supported, but will be removed
66      in the next version (BASE 3.6).
67    </para>
68   
69    <bridgehead>Consider updating to Tomcat 8</bridgehead>
70    <para>
71      We have now tested BASE with Tomcat 8 and it seems to work without
72      any problems. Support for Tomcat 7 will be removed in the next
73      version (BASE 3.6).
74    </para>
75   
76  </sect1>
77 
78  <sect1 id="appendix.update_warnings.3.4">
79    <title>BASE 3.4</title>
80   
81    <bridgehead>Updating from BASE 2.17 is no longer possible</bridgehead>
82    <para>
83      If you are still running an BASE 2.17 (or earlier) BASE version
84      and want to update to BASE 3.4 you must first update to BASE 3.3
85      or earlier.
86    </para>
87   
88    <bridgehead>Web services support has been removed</bridgehead>
89    <para>
90      As announced earlier web services support has been removed in BASE 3.4.
91      If anyone require web services support or similar we recommend using the BASE
92      extensions mechanism to implement exactly what is needed for that project and
93      we also beleive that a simplier API such as JSON is preferable.
94    </para>
95   
96    <bridgehead>PostgreSQL users should change db.dialect</bridgehead>
97    <para>
98      In <filename>base.config</filename> there is a <constant>db.config</constant>
99      setting. Servers running with PostgreSQL as the database should change the
100      dialect to <classname>org.hibernate.dialect.PostgreSQL9Dialect</classname>
101      since the <classname>org.hibernate.dialect.PostgreSQLDialect</classname> has
102      been deprecated.
103    </para>
104   
105  </sect1>
106
107  <sect1 id="appendix.update_warnings.3.3.3">
108    <title>BASE 3.3.3</title>
109 
110    <bridgehead>Remaining quantity</bridgehead>
111    <para>
112      A bug that affected remaining quantity calculations for
113      biomaterial item has been fixed. Existing items may have been
114      saved with incorrect remaining quantity and must be fixed.
115      After installing the BASE 3.3.3 update, the existing
116      remaining quantity values are fix by running a special script.
117      Change directory to <filename class="directory">&lt;base-dir&gt;/bin/</filename> 
118      and issue
119<programlisting>
120./onetimefix.sh remaining_quantity -u &lt;root login&gt; -p &lt;root pwd&gt;
121</programlisting>
122    </para>
123   
124  </sect1>
125 
126  <sect1 id="appendix.update_warnings.3.3">
127    <title>BASE 3.3</title>
128
129    <bridgehead>Content security policy</bridgehead>
130    <para>
131      The BASE web client now set a rather strict <emphasis>Content
132      Security Policy</emphasis> that prevent browsers from executing
133      code (including JavaScript) that is considered unsafe. Some extensions
134      may cease to work due to this. Go to
135      <menuchoice>
136        <guimenu>Administrate</guimenu>
137        <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
138        <guimenuitem>Overview</guimenuitem>
139      </menuchoice> 
140      (after upgrading) to see if there are any warnings about this.
141      Read more in <xref linkend="appendix.web.xml.csp-filter" />
142      for information about how to relax the policy.
143    </para>
144
145    <bridgehead>Java SE 7 is required</bridgehead>
146    <para>
147      BASE now require <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java SE 7</ulink>.
148      Servers with Java SE 6 or older should be updated to Java SE 7 before installing BASE 3.3.
149    </para>
150
151    <bridgehead>Tomcat 7 is required</bridgehead>
152    <para>
153      BASE now require <ulink url="http://tomcat.apache.org/download-70.cgi">Tomcat 7</ulink>.
154      Servers with Tomcat 6 or older should be updated to Tomcat 7 before installing BASE 3.3.
155    </para>
156   
157    <bridgehead>Web services support has been deprecated</bridgehead>
158    <para>
159      The current implementation is most likely not very useful and has limited
160      support for accessing information in BASE. Therefore it has been decided to
161      remove the web services support in BASE 3.4. If anyone require web services
162      support or similar we recommend using the BASE extensions mechanism to implement
163      exactly what is needed for that project and we also beleive that a simplier
164      API such as JSON is preferable.
165    </para>
166
167  </sect1>
168 
169  <sect1 id="appendix.update_warnings.3.2">
170    <title>BASE 3.2</title>
171 
172    <bridgehead>Custom logging implementations must be updated</bridgehead>
173    <para>
174      The plug-in functionality for custom logging has been converted
175      to an extension point. The default database logging will continue
176      to function, but custom logging implementations must be converted
177      to an extension. See <xref linkend="appendix.incompatible.3.2" /> and
178      <xref linkend="extensions_developer.logging" /> for more information.
179    </para>
180 
181  </sect1>
182 
183  <sect1 id="appendix.update_warnings.3.0">
184    <title>BASE 3.0</title>
185   
186    <note>
187      <title>Upgrading to BASE 3 is possible from BASE 2.17 only</title>
188      <para>
189        If your BASE is an older 2.x version you'll need to upgrade
190        to BASE 2.17 before an upgrade to BASE 3 is possible. Also note
191        that since BASE 3.3 we no longer actively test the upgrade
192        script. If upgrading doesn't work for a particular BASE 3.x version
193        (where x &gt; 2) please try to upgrade to BASE 3.2 first and then
194        from BASE 3.2 to BASE 3.x.
195      </para>
196    </note>
197
198    <warning>
199      <title>Make sure that you have a recent backup of the BASE 2.17 database</title>
200      <para>
201        Before starting the upgrade from BASE 2.17 to BASE 3 ensure that you
202        have a recent backup. If the upgrade fails you must restore the
203        2.17 database before you can try again. The upgrade only changes the
204        'static' part of the database, so you do not have to restore the
205        'dynamic' part or the uploaded files.
206      </para>
207    </warning>
208
209    <bridgehead>Old plug-ins and extensions may not work</bridgehead>
210    <para>
211      The BASE API has changed in several places and it is not certain that
212      plug-ins and extensions developed for BASE 2 works with BASE 3. The
213      upgrade will disable all plug-ins and extensions that are currently installed.
214      Before you upgrade we recommend that you go through all (external) plug-ins
215      and check if there is an updated version. The recommended approach
216      is to first upgrade BASE and then install updated versions of plug-ins
217      and extensions following the instructions in <xref 
218      linkend="plugins.installation"/>.
219    </para>
220   
221    <para>
222      If there is no updated version of a specific plug-in you may try
223      a manual re-installation of the old plug-ins. Follow the instructions
224      in <xref linkend="plugins.installation.manual" />.
225    </para>
226   
227    <para>
228      If there is no updated version and the old plug-in doesn't work with
229      BASE 3, you'll need to decide if you really need the plug-in or if
230      the upgrade should wait until a new version of the plug-in
231      has been released.
232    </para>
233   
234    <bridgehead>Batch item importer changes</bridgehead>
235    <para>
236      There are several changes to batch item importers that may affect
237      current workflows and file templates used for importing data.
238    </para>
239   
240    <itemizedlist>
241      <listitem>
242        <para>
243          Sample and extract importers: The 'pooled' column is no longer used.
244          Instead a 'parent type' column should be used with
245          the parent type as a string value (BIOSOURCE, SAMPLE or EXTRACT).
246          Existing importer configurations and file templates may have to be
247          updated. If no parent type is specified the sample importer assumes
248          a biosource and the extract importer assumes a sample.
249        </para>
250      </listitem>
251      <listitem>
252        <para>
253          Labeled extract importer: This has been deprecated and it is recommended
254          that the <emphasis>Extract importer</emphasis> is used instead.
255          We recommend that existing labeled extract importer configurations are re-created as extract
256          importer configurations. The old labeled extract importer can be
257          re-enabled, but note that the existing configurations still need
258          to be changed due to the 'pooled' column is no longer used.
259        </para>
260      </listitem>
261      <listitem>
262        <para>
263          Hybridization importer: This has been deprecated and we recommend
264          that the <emphasis>Physical bioassay importer</emphasis> is used instead.
265          Existing hybridization importer configurations should be re-created as
266          physical bioassay importer configurations.
267        </para>
268      </listitem>
269      <listitem>
270        <para>
271          Scan importer: This has been deprecated and it is recommended
272          that the <emphasis>Derived bioassay importer</emphasis> is used instead.
273          Existing scan importer configurations should be re-created as derived
274          bioassay importer configurations.
275        </para>
276      </listitem>
277    </itemizedlist>
278   
279    <note>
280      The deprecated importers can be re-enabled by an administrator from the
281      <menuchoice>
282        <guimenu>Administrate</guimenu>
283        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
284        <guimenuitem>Overview</guimenuitem>
285      </menuchoice> page, but they are
286      lacking features that are available in the new importers so this is not
287      something that we recommend.
288    </note>
289   
290    <bridgehead>MySQL and PostgreSQL versions</bridgehead>
291    <para>
292      We have only tested BASE 3 with PostgreSQL 9.1. If anyone
293      experiences any issues with earlier PostgreSQL versions, we
294      recommend an upgrade to PostgreSQL 9.1. This is a change since
295      BASE 2 which was tested with PostgreSQL 8.4. Even though BASE 3
296      may work with older PostgreSQL versions, we don't have the resources
297      needed to test and provide support for it.
298    </para>
299   
300    <para>
301      We have only tested BASE 3 with MySQL 5.1 (no change since BASE 2).
302      If anyone experiences any issues with earlier (or later) MySQL versions,
303      we recommend an upgrade/downgrade to MySQL 5.1.
304    </para>
305 
306  </sect1>
307 
308  <sect1 id="appendix.update_warnings.2.x">
309    <title>All BASE 2.x releases</title>
310   
311    <para>
312      We only support updating to BASE 3 from BASE 2.17. If you have an older BASE
313      version and wish to update to BASE 3, you first have to upgrade to BASE 2.17.
314      BASE 2.17 can be downloaded from the <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
315      download page</ulink>. Documentation for BASE 2.17 is available as part of the
316      download and at <ulink url="http://base.thep.lu.se/chrome/site/2.17/html/index.html"
317      >http://base.thep.lu.se/chrome/site/2.17/html/index.html</ulink>.
318    </para>
319
320  </sect1>
321 
322</appendix>
323
Note: See TracBrowser for help on using the repository browser.