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

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

Addresses #516. Upgrade and installation done.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 23.8 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 3350 2007-05-19 07:56:35Z 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 several 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                  directory, 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                  building 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
263      <varlistentry>
264        <term>Java</term>
265        <listitem>
266          <para>
267            Download and install Java SDK 1.5, available from
268            <ulink url="http://java.sun.com/" />. Make sure that you
269            download the JDK version (<emphasis>not</emphasis> the JRE
270            version). <command>Java 6 is currently not
271            supported</command>.
272          </para>
273        </listitem>
274      </varlistentry>
275
276      <varlistentry>
277        <term>Tomcat</term>
278        <listitem>
279          <para>
280            Download and install tomcat 5.5.16 or later, available
281            from <ulink
282            url="http://jakarta.apache.org/tomcat/" />
283            <important>
284              You MUST make sure that Tomcat uses the SERVER mode of
285              the Java run time engine
286              (see <ulink
287              url="http://lev.thep.lu.se/trac/base/ticket/99">ticket:99</ulink>).
288            </important>
289            On Linux you do this by setting the environment variable:
290            <code>CATALINA_OPTS</code> to <code>-server</code>. It is
291            also a good idea to specify the maximum allowed memory to
292            use: <code>-server -Xmx500m</code> sets it to 500
293            megabytes. Basically add the next line close to the top of
294            the <filename>catalina.sh</filename> script that comes
295            with tomcat
296            (directory <filename
297            class="direcotry">bin</filename>): <programlisting>
298CATALINA_OPTS="-server -Xmx500m"
299</programlisting>
300          </para>
301          <para>
302            For more information about Tomcat options see
303            <ulink url="http://www.chemaxon.com/jchem/doc/admin/tomcat.html" />.
304          </para>
305        </listitem>
306      </varlistentry>
307
308      <varlistentry>
309        <term>Set up SQL database</term>
310        <listitem>
311          <para>
312            BASE 2
313            utilize <ulink
314            url="http://www.hibernate.org/">Hibernate</ulink> for
315            object persistence to a relational database. Hibernate
316            supports many database engines, but so far we only work
317            with <ulink url="http://www.mysql.com">MySQL</ulink>
318            and <ulink
319            url="http://www.postgresql.org/">PostgreSQL</ulink>.
320          </para>
321
322          <variablelist>
323            <varlistentry>
324              <term>MySQL</term>
325              <listitem>
326                <para>
327                  Download and install MySQL (tested with version
328                  5.0), available from
329                  <ulink url="http://www.mysql.com/" />. You need to
330                  be able to connect to the server over TCP, so
331                  the <emphasis>skip-networking</emphasis> option
332                  must <command>not</command> be used. The InnoDB
333                  table engine is also needed, so don't disable them
334                  (not that you would) but you may want to tune the
335                  InnoDB behaviour before creating BASE
336                  databases. BASE comes pre-configured for MySQL so
337                  there is no need to change database settings in the
338                  BASE configuration files.
339                </para>
340              </listitem>
341            </varlistentry>
342            <varlistentry>
343              <term>PostgreSQL</term>
344              <listitem>
345                <para>
346                  PostgreSQL 8.0 seems to be working very well with
347                  BASE and Hibernate. Download and install PostgreSQL,
348                  available from
349                  <ulink url="http://www.postgresql.org/" />. you must
350                  edit
351                  your <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
352                  file. Uncomment the settings for Postgres and
353                  comment out the settings for MySQL.
354                </para>
355              </listitem>
356            </varlistentry>
357          </variablelist>
358
359        </listitem>
360      </varlistentry>
361
362      <varlistentry>
363        <term>BASE (download and unpacking)</term>
364        <listitem>
365          <para>
366            <ulink
367            url="http://base.thep.lu.se/wiki/DownloadPage">Download
368            BASE</ulink> and unpack the downloaded file,
369            i.e. <command>tar zxpf base-...tar.gz</command>. If you
370            prefer to have the bleeding edge version of BASE, perform
371            a checkout of the source from the subversion repository
372            (subversion checkout instructions at
373            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
374            trac site</ulink>).
375          </para>
376          <para>
377            If you choose to download the binary package, skip to the
378            next item. The rest of us, read on and compile BASE 2. If
379            you downloaded a source distribution, unpack the
380            downloaded file <command>tar zxpf
381            base-...src.tar.gz</command>, or you may have performed a
382            subversion checkout.  Change to the 'root' base2
383            directory, and issue <command>ant
384            package.bin</command>. This will create a binary package
385            in the base2 'root' directory. Unpack this new package
386            (outside of the source file hierarchy), and from now on
387            the instructions are the same irrespective where you got
388            the binary package.
389          </para>
390          <para>
391            <emphasis>This section is intended for advanced users and
392              programmers only. In cases when you want to change the
393              BASE code and try out personalized features it may be
394              advantageous to run the tweaked BASE server against the
395              development tree. Instructions on how to accomplish this
396              is available in the
397              <ulink
398              url="http://base.thep.lu.se/chrome/site/doc/development/build.html">building
399              BASE document</ulink>. When you return back after
400              compiling in the subversion tree you can follow the
401              instruction here (with obvious changes to
402              paths).</emphasis>
403          </para>
404        </listitem>
405      </varlistentry>
406
407      <varlistentry>
408        <term>BASE (database engine)</term>
409        <listitem>
410          <para>
411            Instructions for MySQL and PostgreSQL are available
412            below. The database names (base2 and base2dynamic is used
413            here), the <emphasis>db_user</emphasis>, and
414            the <emphasis>db_password</emphasis> can be changed during
415            the creation of the databases. It is recommended to change
416            the <emphasis>db_password</emphasis>, the other changes
417            can be made if desired. The database names,
418            the <emphasis>db_user</emphasis>, and
419            the <emphasis>db_password</emphasis> are needed in a later
420            step below when configuring BASE.
421          </para>
422          <note>
423            Note that the <emphasis>db_user</emphasis> name
424            and <emphasis>db_password</emphasis> set here is used
425            internally by BASE in communication with the database and
426            is never used to log on to the BASE application.
427          </note>
428          <variablelist>
429            <varlistentry>
430              <term>MySQL</term>
431              <listitem>
432                <para>
433                  Create a new database for BASE, and add a
434                  <emphasis>db_user</emphasis> with at least
435                  <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
436                  <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
437                  <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
438                  <emphasis>INDEX</emphasis>,
439                  and <emphasis>ALTER</emphasis> permission for the
440                  new database. To do this, connect to your MySQL
441                  server and issue the next lines:
442                  <programlisting>
443CREATE DATABASE base2;
444CREATE DATABASE base2dynamic;
445GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
446GRANT ALL ON base2dynamic.* TO db_user@localhost;
447</programlisting>
448                </para>
449                <para>
450                  The <filename>/path/to/base/misc/sql/createdb.mysql.sql</filename>
451                  file contains the above statements and can be used
452                  by the <filename>mysql</filename> command-line tool
453                  (remember to edit
454                  the <emphasis>db_user</emphasis>,
455                  <emphasis>db_password</emphasis>,
456                  and the database names in the script file before
457                  executing the command): <command>mysql -uroot -p
458                  &lt; ./misc/sql/createdb.mysql.sql</command>. The
459                  header in the script file contains further
460                  information about the script.
461                </para>
462              </listitem>
463            </varlistentry>
464            <varlistentry>
465              <term>PostgreSQL</term>
466              <listitem>
467                <para>
468                  Create a new database for BASE, and add a
469                  <emphasis>db_user</emphasis> with the proper
470                  privileges. To do this, log in as your PostgreSQL
471                  user and issue these lines (omit comments):
472                  <programlisting>
473createuser db_user -P
474  # this will prompt for an password for the new user, and issue two
475  # more question that should be answered with character 'n' for no.
476createdb --owner db_user --encoding UNICODE base2
477psql base2
478  # this will start the psql command line tool. Issue the next line
479  # within the tool and quit with a '\q'.
480CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";
481</programlisting>
482                  The <filename>/path/to/base/misc/sql/createdb.postgresql.sql</filename>
483                  file contains the above statements and can be used
484                  by the <filename>psql</filename> command-line tool:
485                  <command>psql -f ./misc/sql/createdb.posgres.sql
486                    template1</command> The header in the script file
487                  contains further information about the script.
488                </para>
489              </listitem>
490            </varlistentry>
491          </variablelist>
492        </listitem>
493      </varlistentry>
494
495      <varlistentry>
496        <term>BASE (file storage setup)</term>
497        <listitem>
498          <para>
499            An area for file storage must be setup. Create an empty
500            directory in a proper location in your file system, and
501            set the owner to be the same as the one that the tomcat
502            server will be running as. Remember this location for
503            later use.
504          </para>
505        </listitem>
506      </varlistentry>
507
508      <varlistentry>
509        <term>BASE (configuration)</term>
510        <listitem>
511          <para>
512            Basic BASE configuration is done in
513            <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>:
514            <itemizedlist>
515              <listitem>
516                Uncomment the database engine section that match your setup.
517              </listitem>
518              <listitem>
519                Modify the <emphasis>db.url</emphasis>,
520                <emphasis>db.dynamic.catalog</emphasis>,
521                <emphasis>db.username</emphasis>,
522                and <emphasis>db.password</emphasis> settings to match
523                your choice above. (<emphasis>database host and
524                database name (e.g. base2)</emphasis>,
525                <emphasis>e.g. base2dynamic</emphasis>,
526                <emphasis>db_user</emphasis>, and
527                and <emphasis>db_password</emphasis>, respectively.)
528              </listitem>
529              <listitem>
530                Modify the <emphasis>userfiles</emphasis> setting to
531                match your choice above.
532              </listitem>
533            </itemizedlist>
534          </para>
535          <para>
536            <emphasis>Optional but recommended.</emphasis> You may want
537            to modify extended properties to fit your needs. Extended
538            properties are defined in
539            <filename>/path/to/base/www/WEB-INF/classes/extended-properties.xml</filename>.
540            There is an administrator <ulink
541            url="http://base.thep.lu.se/chrome/site/doc/admin/extended-properties.html">document
542              discussing extended properties</ulink> available.
543          </para>
544        </listitem>
545      </varlistentry>
546
547      <varlistentry>
548        <term>BASE (database initialization)</term>
549        <listitem>
550          <para>
551            Change directory to
552            <filename class="directory">/path/to/base/bin</filename>
553            and run <filename>initdb.sh</filename> as <programlisting>
554./initdb.sh base_root_password password
555</programlisting>
556            <important>
557            The <emphasis>base_root_password</emphasis> you use here
558            is given to the BASE web application
559            user <emphasis>root</emphasis>. There is no supported way
560            to change the <emphasis>root</emphasis> account name.
561            </important>
562            If the initialisation script fail, it is most probably a
563            problem related to the underlying database. Make sure that
564            the database accepts network connection and make sure that
565            <emphasis>db_user</emphasis> has proper credentials.
566          </para>
567        </listitem>
568      </varlistentry>
569
570      <varlistentry>
571        <term>BASE and tomcat</term>
572        <listitem>
573          <para>
574            Either move the <filename
575            class="directory">/path/to/base/www</filename> directory
576            to the tomcat <filename class="directory">webapps</filename>
577            directory or create a symbolic link from the tomcat
578            <filename class="directory">webapps</filename> directory to
579            the <filename class="directory">/path/to/base/www</filename>
580            directory <programlisting>
581cd /path/to/tomcat/webapps
582ln -s /path_to_base/www base2
583</programlisting>
584            Start/restart tomcat, and try http://hostname:8080/base2
585            (change <emphasis>hostname</emphasis> to your hostname) in
586            your favourite browser. BASE log-in page should appear
587            after a few seconds.
588          </para>
589        </listitem>
590      </varlistentry>
591
592      <varlistentry>
593        <term>BASE, apache, and apache/tomcat connector</term>
594        <listitem>
595          <para>
596            <emphasis>This step is optional</emphasis>.
597          </para>
598          <para>
599            If you want run the tomcat server through the apache web
600            server, you need to install the apache version 2 web
601            server, available
602            from <ulink
603            url="http://www.apache.org/">http://www.apache.org/</ulink>,
604            and a apache-tomcat connector, available
605            from <ulink
606            url="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</ulink>.
607            So, we got you there;-) To be honest, this step is not
608            really well documented since we previously used SuSE 9.3
609            on our demo/test server, and apache/tomcat/mod_jk comes
610            pre-installed. The current server does not use the
611            apache/tomcat connector. What you need to do is something
612            like this
613            <itemizedlist>
614              <listitem>
615                Get that tomcat server running in stand-alone
616                mode.
617              </listitem>
618              <listitem>
619                Get the apache 2 server running.
620              </listitem>
621              <listitem>
622                Install mod_jk. Note, different version are used for
623                apache 1.3 and 2. In SuSE 9.3 this step is done by
624                installing <filename>mod_jk-ap20</filename>.
625              </listitem>
626              <listitem>
627                Create a <filename>workers.properties</filename> file
628                in the
629                tomcat <filename class="directory">base</filename>
630                directory (commonly copied from a template).
631              </listitem>
632              <listitem>
633                Create a <filename>jk.conf</filename> file in the
634                apache <filename class="directory">conf</filename>
635                directory (commonly copied from a template), and make
636                sure that <emphasis>jk</emphasis> is added to the
637                modules to be loaded when apache starts.
638              </listitem>
639              <listitem>
640                In <filename>jk.conf</filename> add the lines below
641                and change paths appropriately. <programlisting>
642# The following lines makes apache aware of the location of
643# the /base2 context
644Alias /base2 "/srv/www/tomcat5/base/webapps/base2"
645&lt;Directory "/srv/www/tomcat5/base/webapps/base2"&gt;
646Options Indexes FollowSymLinks
647allow from all
648&lt;/Directory&gt;
649# The following lines mounts all base2 jsp files to tomcat
650JkMount /base2 ajp13
651JkMount /base2/* ajp13
652# The following lines prohibits users from directly accessing WEB-INF
653&lt;Location "/base2/WEB-INF/"&gt;
654AllowOverride None
655deny from all
656&lt;/Location&gt;
657</programlisting>
658              </listitem>
659            </itemizedlist>
660            You must restart the apache and the tomcat server after above steps.
661          </para>
662        </listitem>
663      </varlistentry>
664
665      <varlistentry>
666        <term>Setup done!</term>
667        <listitem>
668          <para>
669            Happy BASEing. Now you can log on to your BASE 2 server as
670            user <emphasis>root</emphasis> (use
671            the <emphasis>base_root_password</emphasis> from the
672            database initialization step above). You should begin with
673            creating a couple user accounts, for more information on
674            how to create user accounts please refer to
675            <xref linkend="user_administration"/>.
676          </para>
677        </listitem>
678      </varlistentry>
679
680    </variablelist>
681
682  </sect1>      <!-- Installation instructions -->
683
684
685  <sect1 id="installation_upgrade.migration">
686    <title>Migration instructions</title>
687    <para></para>
688  </sect1>      <!-- Migration instructions -->
689
690  <sect1 id="installation_upgrade.jobagents">
691    <title>Installing job agents</title>
692    <para>TODO</para>
693  </sect1>
694
695</chapter>
Note: See TracBrowser for help on using the repository browser.