source: trunk/doc/src/docbook/admindoc/installation_upgrade.xml @ 3299

Last change on this file since 3299 was 3299, checked in by Jari Häkkinen, 14 years ago

Addresses #516.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 16.3 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter 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: installation_upgrade.xml 3299 2007-05-07 13:13:27Z jari $
7
8  Copyright (C) Authors contributing to this file.
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 2
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 this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<chapter id="installation_upgrade">
30  <?dbhtml dir="installation_upgrade"?>
31
32  <title>Installation, migration, and upgrade instructions</title>
33
34  <note>
35    These instructions apply only to the BASE release which this
36    document is a part of.
37  </note>
38
39  <para>
40    This chapter is divided into three parts. First, the process of
41    upgrading a BASE 2 server is described. It is assumed that there
42    is a running server. Then, the first time installation
43    instructions follows, and the chapter is concluded with
44    information on how to migrate data from a BASE 1.2.17 server to a
45    BASE 2 server.
46  </para>
47
48  <para>
49    The first time installation is expected to be performed only once,
50    and optionally followed by a migration. The migration can only be
51    done to a pristine (empty) BASE 2 server, and migration from
52    several BASE 1 installations to one BASE 2 server is not
53    supported.
54  </para>
55
56  <para>
57    The instructions here assume
58    that <ulink url="http://tomcat.apache.org/">tomcat</ulink> is used
59    on the server side. Other servlet engines may work but we only
60    test tomcat.
61  </para>
62
63
64  <sect1 id="installation_upgrade.upgrade">
65    <title>Upgrade instructions</title>
66
67    <important>
68      Note to PostgreSQL users: Upgrading BASE to versions earlier
69      than v2.2 is not be safe with an PostgreSQL database engine due
70      to a bug in Hibernate. The problem is reported to Hibernate
71      developers. There now exists a workaround for this problem. Read
72      more about the workaround on
73      the <ulink
74      url="http://base.thep.lu.se/wiki/UpgradePostgres">Upgrading a
75      Postgres database prior to BASE 2.2</ulink> page. This fix is
76      not needed for the release which this document is a part of.
77    </important>
78
79    <para>
80      As always, backup your database before attempting an
81      upgrade. The BASE team performs extensive testing before
82      releasing a new version of BASE but there are always a
83      possibility for unexpected events during upgrades. In upgrades
84      requiring a change in the underlying database there is no
85      (supported) way to revert to a previous version of BASE using
86      BASE tools, you need to use your backup for this use case.
87    </para>
88
89    <para>
90      The strategy here is to install the new BASE release to another
91      directory than the one in use. This requires transfer of
92      configuration settings to the new install but more on that
93      below.
94    </para>
95
96    <variablelist>
97      <varlistentry>
98        <term>Shut down the tomcat server</term>
99        <listitem>
100          <para>
101            If the BASE application is not shut down already, it is
102            time to do it now. Do something like <command>sudo
103            /etc/init.d/tomcat5.5 stop</command>
104          </para>
105        </listitem>
106      </varlistentry>
107
108      <varlistentry>
109        <term>Rename your current server</term>
110        <listitem>
111          <para>
112            Rename your current BASE 2 installation <command>mv
113              /path/to/base /path/to/base_old</command>.
114          </para>
115        </listitem>
116      </varlistentry>
117
118      <varlistentry>
119        <term>Download and unpack BASE</term>
120        <listitem>
121          <para>
122            There are severeal ways to download BASE. Please refer to
123            section <xref linkend="resources.home_page.download"/> for
124            information on downloading BASE, and select the item
125            matching your download option:
126          </para>
127
128          <variablelist>
129            <varlistentry>
130              <term><emphasis>Pre-compiled package</emphasis></term>
131              <listitem>
132                <para>
133                  If you selected to download a pre-compiled package,
134                  unpack the downloaded file with <command>tar zxpf
135                  base-...tar.gz</command>.
136                </para>
137              </listitem>
138            </varlistentry>
139
140            <varlistentry>
141              <term><emphasis>Source package</emphasis></term>
142              <listitem>
143                <para>
144                  If you selected to download a source package, unpack
145                  the downloaded file with <command>tar zxpf
146                  base-...src.tar.gz</command>. Change to the new
147                  direcotry, and issue <command>ant
148                  package.bin</command>. This will create a binary
149                  package in the current directory. Unpack this new
150                  package (outside of the source file hierarchy).
151                </para>
152              </listitem>
153            </varlistentry>
154
155            <varlistentry>
156              <term><emphasis>Subversion checkout</emphasis></term>
157              <listitem>
158                <para>
159                  This option is for advanced users only and is not
160                  covered here. Please refer
161                  to <ulink
162                  url="http://base.thep.lu.se/chrome/site/doc/development/build.html">the
163                  builing BASE document</ulink> for information on
164                  this download option.
165                </para>
166              </listitem>
167            </varlistentry>
168
169          </variablelist>
170        </listitem>
171
172      </varlistentry>
173
174      <varlistentry>
175        <term>Transfer files and settings</term>
176        <listitem>
177          <para>
178            Settings from the previous installation must be
179            transferred to the new installation. This is most easily
180            done by comparing the configuration files from the
181            previous install with the new files. Do not just copy the
182            old files to the new install since new options may have
183            appeared.
184          </para>
185          <para>
186            In the main BASE configuration file,
187            <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>,
188            fields that needs to be transferred are usually
189            <emphasis>db.username</emphasis>,
190            <emphasis>db.password</emphasis>,
191            and <emphasis>userfiles</emphasis>.
192          </para>
193          <para>
194            Local settings in the raw data
195            tables, <filename>/path/to/base/www/WEB-INF/classes/raw-data-types.xml</filename>,
196            may need to be transferred.
197          </para>
198        </listitem>
199      </varlistentry>
200
201      <varlistentry>
202        <term>Updating database schema</term>
203        <listitem>
204          <para>
205            It is recommended that you also perform an update of your
206            database schema.  Running the update scripts are not
207            always necessary when upgrading BASE, but the running the
208            update scripts are safe even in cases when there is no
209            need to run them. Change directory
210            to <filename
211            class="direcotry">/path/to/base/bin/</filename> and issue
212            <programlisting>
213sh ./updatedb.sh <emphasis>base_root_password</emphasis>
214sh ./updateindexes.sh <emphasis>base_root_password</emphasis>
215</programlisting>
216            where <emphasis>base_root_password</emphasis> is the
217            password for the root user account within the BASE
218            application.
219          </para>
220        </listitem>
221      </varlistentry>
222
223      <varlistentry>
224        <term>Remove tomcat cache</term>
225        <listitem>
226          <para>
227            As tomcat user, remove cached files and directories. Do
228            something like
229            <programlisting>
230cd /usr/share/apache-tomcat-5.5.15/
231rm -rf work/Catalina
232</programlisting>
233          </para>
234        </listitem>
235      </varlistentry>
236
237      <varlistentry>
238        <term>Start tomcat</term>
239        <listitem>
240          <para>
241            Start the tomcat server: <command>sudo
242              /etc/init.d/tomcat5.5 start</command>
243          </para>
244        </listitem>
245      </varlistentry>
246
247    </variablelist>
248
249    <para>
250      Done! Upgrade of BASE is finished.
251    </para>
252
253  </sect1>      <!-- Upgrade instructions -->
254
255
256
257
258  <sect1 id="installation_upgrade.installation">
259    <title>Installation instructions</title>
260
261    <variablelist>
262      <varlistentry>
263        <term>Set up SQL database</term>
264        <listitem>
265          <para>
266            BASE 2
267            utilize <ulink
268            url="http://www.hibernate.org/">Hibernate</ulink> for
269            object persistence to a relational database. Hibernate
270            supports many database engines, but so far we only work
271            with <ulink url="http://www.mysql.com">MySQL</ulink>
272            and <ulink
273            url="http://www.postgresql.org/">PostgreSQL</ulink>.
274          </para>
275
276          <variablelist>
277            <varlistentry>
278              <term>MySQL</term>
279              <listitem>
280                <para>
281                  Download and install MySQL (tested with version
282                  5.0), available from
283                  <ulink
284                  url="http://www.mysql.com/">http://www.mysql.com/</ulink>. You
285                  need to be able to connect to the server over TCP,
286                  so the <emphasis>skip-networking</emphasis> option
287                  must <command>not</command> be used. The InnoDB
288                  table engine is also needed, so don't disable them
289                  (not that you would) but you may want to tune the
290                  InnoDB behaviour before creating BASE
291                  databases. BASE comes pre-configured for MySQL so
292                  there is no need to change database settings in the
293                  BASE configuration files.
294                </para>
295              </listitem>
296            </varlistentry>
297            <varlistentry>
298              <term>PostgreSQL</term>
299              <listitem>
300                <para>
301                  PostgreSQL 8.0 seems to be working very well with
302                  BASE and Hibernate. Download and install PostgreSQL,
303                  avaialble
304                  from <ulink
305                  url="http://www.postgresql.org/">http://www.postgresql.org/</ulink>. you
306                  must edit
307                  your <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
308                  file. Uncomment the settings for Postgres and
309                  comment out the settings for MySQL.
310                </para>
311              </listitem>
312            </varlistentry>
313          </variablelist>
314
315        </listitem>
316      </varlistentry>
317
318      <varlistentry>
319        <term>Java</term>
320        <listitem>
321          <para>
322            Download and install Java SDK 1.5, available
323            from <ulink
324            url="http://java.sun.com/">http://java.sun.com/</ulink>. Make
325            sure that you download the JDK version
326            (<emphasis>not</emphasis> the JRE version). <command>Java
327            6 is currently not supported</command>.
328          </para>
329        </listitem>
330      </varlistentry>
331
332      <varlistentry>
333        <term>BASE (download and unpacking)</term>
334        <listitem>
335          <para>
336            <ulink
337            url="http://base.thep.lu.se/wiki/DownloadPage">Download
338            BASE</ulink> and unpack the downloaded file,
339            i.e. <command>tar zxpf base-...tar.gz</command>. If you
340            prefer to have the bleeding edge version of BASE, perform
341            a checkout of the source from the subversion repository
342            (subversion checkout instructions at
343            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
344            trac site</ulink>).
345          </para>
346          <para>
347            If you choose to download the binary package, skip to the
348            next item. The rest of us, read on and compile BASE 2. If
349            you downloaded a source distribution, unpack the
350            downloaded file <command>tar zxpf
351            base-...src.tar.gz</command>, or you may have performed a
352            subversion checkout.  Change to the 'root' base2
353            directory, and issue <command>ant
354            package.bin</command>. This will create a binary package
355            in the base2 'root' directory. Unpack this new package
356            (outside of the source file hierarchy), and from now on
357            the instructions are the same irrespective where you got
358            the binary package.
359          </para>
360          <para>
361            <emphasis>This section is intended for advanced users and
362              programmers only. In cases when you want to change the
363              BASE code and try out personalized features it may be
364              advantageous to run the tweaked BASE server against the
365              development tree. Instructions on how to accomplish this
366              is available in the
367              <ulink
368              url="http://base.thep.lu.se/chrome/site/doc/development/build.html">building
369              BASE document</ulink>. When you return back after
370              compiling in the subversion tree you can follow the
371              instruction here (with obvious changes to
372              paths).</emphasis>
373          </para>
374        </listitem>
375      </varlistentry>
376
377      <varlistentry>
378        <term>BASE (database engine)</term>
379        <listitem>
380          <para>
381            Instructions for MySQL and PostgreSQL are available
382            below. The database names, the <emphasis>user</emphasis>,
383            and the <emphasis>password</emphasis> can be changed
384            during the creation of the databases. It is recommended to
385            change the <emphasis>password</emphasis>, the other
386            changes can be made if required. The database names,
387            the <emphasis>user</emphasis>, and
388            the <emphasis>password</emphasis> are needed in a later
389            step below when configuring BASE.
390          </para>
391          <variablelist>
392            <varlistentry>
393              <term>MySQL</term>
394              <listitem>
395                <para>
396                  Create a new database for BASE, and add a
397                  <emphasis>user</emphasis> with at least
398                  <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
399                  <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
400                  <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
401                  <emphasis>INDEX</emphasis>,
402                  and <emphasis>ALTER</emphasis> permission for the
403                  new database. To do this, connect to your MySQL
404                  server and issue the next lines:
405                  <programlisting>
406CREATE DATABASE base2;
407CREATE DATABASE base2dynamic;
408GRANT ALL ON base2.* TO base2user@localhost IDENTIFIED BY 'password';
409GRANT ALL ON base2dynamic.* TO base2user@localhost;
410</programlisting>
411                </para>
412                <para>
413                  The <filename>/path/to/base/misc/sql/createdb.mysql.sql</filename>
414                  file contains the above statements and can be used
415                  by the <filename>mysql</filename> command-line tool
416                  (remember to edit
417                  the <emphasis>user</emphasis>, <emphasis>password</emphasis>,
418                  and the database names in the script file before
419                  executing the command): <command>mysql -uroot -p
420                  &lt; ./misc/sql/createdb.mysql.sql</command>. The
421                  header in the script file contains further
422                  information about the script.
423                </para>
424              </listitem>
425            </varlistentry>
426            <varlistentry>
427              <term>PostgreSQL</term>
428              <listitem>
429                <para>
430                  Create a new database for BASE, and add a
431                  <emphasis>user</emphasis> with the proper
432                  privileges. To do this, log in as your PostgreSQL
433                  user and issue these lines (omit comments):
434                  <programlisting>
435createuser base2user -P
436  # this will prompt for an password for the new user, and issue two
437  # more question that should be answered with character 'n' for no.
438createdb --owner base2user --encoding UNICODE base2
439psql base2
440  # this will start the psql command line tool. Issue the next line
441  # within the tool and quit with a '\q'.
442CREATE SCHEMA "dynamic" AUTHORIZATION "base2user";
443</programlisting>
444                  The <filename>/path/to/base/misc/sql/createdb.postgresql.sql</filename>
445                  file contains the above statements and can be used
446                  by the <filename>psql</filename> command-line tool:
447                  <command>psql -f ./misc/sql/createdb.posgres.sql
448                    template1</command> The header in the script file
449                  contains further information about the script.
450                </para>
451              </listitem>
452            </varlistentry>
453          </variablelist>
454        </listitem>
455      </varlistentry>
456
457      <varlistentry>
458        <term>BASE (file storage setup)</term>
459        <listitem>
460          <para>
461            An area for file storage must be setup. Create an empty
462            directory in a proper location in your file system, and
463            set the owner to be the same as the one that the tomcat
464            server will be running as. Remember this location for
465            later use.
466          </para>
467        </listitem>
468      </varlistentry>
469
470      <varlistentry>
471        <term>BASE (configuration)</term>
472        <listitem>
473          <para>
474          </para>
475        </listitem>
476      </varlistentry>
477
478      <varlistentry>
479        <term></term>
480        <listitem>
481          <para>
482          </para>
483        </listitem>
484      </varlistentry>
485    </variablelist>
486
487
488  </sect1>      <!-- Installation instructions -->
489
490
491  <sect1 id="installation_upgrade.migration">
492    <title>Migration instructions</title>
493    <para></para>
494  </sect1>      <!-- Migration instructions -->
495
496</chapter>
Note: See TracBrowser for help on using the repository browser.