source: branches/2.4-stable/doc/src/docbook/admindoc/installation_upgrade.xml @ 3744

Last change on this file since 3744 was 3744, checked in by Martin Svensson, 15 years ago

Fixes #763

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 40.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 3744 2007-09-17 13:04:16Z martin $
7
8  Copyright (C) 2007 Jari Hakkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
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, setup, 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 four parts. First, the process of
41    upgrading a BASE 2 server is described. Followed by set up of job
42    agents. (For these two first parts it is assumed that there is a
43    running server.) Then, the first time installation instructions
44    follows, and the chapter is concluded with information on how to
45    migrate data from a BASE 1.2.17 server to a BASE 2 server.
46  </para>
47
48  <para>
49    The first time installation is only to be performed once,
50    optionally followed by a migration. The migration can only be done
51    to a pristine (empty) BASE 2 server with one exception; The
52    migration can be restarted if it fails during the RawBioAssaysData
53    transfer, for all other failure points the migration has to be
54    restarted with an empty database. Migration from several BASE 1
55    installations to one BASE 2 server is not supported.
56  </para>
57
58  <para>
59    The instructions here assume
60    that <ulink url="http://tomcat.apache.org/">tomcat</ulink> is used
61    on the server side. Other servlet engines may work but we only
62    test tomcat.
63  </para>
64
65
66  <sect1 id="installation_upgrade.upgrade">
67    <title>Upgrade instructions</title>
68
69    <important>
70      <title>Note to PostgreSQL users</title>
71      Upgrading BASE to versions earlier
72      than v2.2 is not be safe with an PostgreSQL database engine due
73      to a bug in Hibernate. The problem is reported to Hibernate
74      developers. There now exists a workaround for this problem. Read
75      more about the workaround on
76      the <ulink
77      url="http://base.thep.lu.se/wiki/UpgradePostgres">Upgrading a
78      Postgres database prior to BASE 2.2</ulink> page. This fix is
79      not needed for the release which this document is a part of.
80    </important>
81
82    <para>
83      As always, backup your database before attempting an
84      upgrade. The BASE team performs extensive testing before
85      releasing a new version of BASE but there are always a
86      possibility for unexpected events during upgrades. In upgrades
87      requiring a change in the underlying database there is no
88      (supported) way to revert to a previous version of BASE using
89      BASE tools, you need to use your backup for this use case.
90    </para>
91
92    <para>
93      The strategy here is to install the new BASE release to another
94      directory than the one in use. This requires transfer of
95      configuration settings to the new install but more on that
96      below.
97    </para>
98
99    <variablelist>
100      <varlistentry>
101        <term>Shut down the tomcat server</term>
102        <listitem>
103          <para>
104            If the BASE application is not shut down already, it is
105            time to do it now. Do something like <command>sudo
106            /etc/init.d/tomcat5.5 stop</command>
107          </para>
108        </listitem>
109      </varlistentry>
110
111      <varlistentry>
112        <term>Rename your current server</term>
113        <listitem>
114          <para>
115            Rename your current BASE 2 installation <command>mv
116              /path/to/base /path/to/base_old</command>.
117          </para>
118        </listitem>
119      </varlistentry>
120
121      <varlistentry>
122        <term>Download and unpack BASE</term>
123        <listitem>
124          <para>
125            There are several ways to download BASE. Please refer to
126            section <xref linkend="resources.home_page.download"/> for
127            information on downloading BASE, and select the item
128            matching your download option:
129          </para>
130
131          <variablelist>
132            <varlistentry>
133              <term><emphasis>Pre-compiled package</emphasis></term>
134              <listitem>
135                <para>
136                  If you selected to download a pre-compiled package,
137                  unpack the downloaded file with <command>tar zxpf
138                  base-...tar.gz</command>.
139                </para>
140              </listitem>
141            </varlistentry>
142
143            <varlistentry>
144              <term><emphasis>Source package</emphasis></term>
145              <listitem>
146                <para>
147                  If you selected to download a source package, unpack
148                  the downloaded file with <command>tar zxpf
149                  base-...src.tar.gz</command>. Change to the new
150                  directory, and issue <command>ant
151                  package.bin</command>. This will create a binary
152                  package in the current directory. Unpack this new
153                  package (outside of the source file hierarchy).
154                </para>
155              </listitem>
156            </varlistentry>
157
158            <varlistentry>
159              <term><emphasis>Subversion checkout</emphasis></term>
160              <listitem>
161                <para>
162                  This option is for advanced users only and is not
163                  covered here. Please refer to
164                  <xref linkend="core_ref.build"/> for information on
165                  this download option.
166                </para>
167              </listitem>
168            </varlistentry>
169
170          </variablelist>
171        </listitem>
172
173      </varlistentry>
174
175      <varlistentry>
176        <term>Transfer files and settings</term>
177        <listitem>
178          <para>
179            Settings from the previous installation must be
180            transferred to the new installation. This is most easily
181            done by comparing the configuration files from the
182            previous install with the new files. Do not just copy the
183            old files to the new install since new options may have
184            appeared.
185          </para>
186          <para>
187            In the main BASE configuration file,
188            <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>,
189            fields that needs to be transferred are usually
190            <emphasis>db.username</emphasis>,
191            <emphasis>db.password</emphasis>,
192            and <emphasis>userfiles</emphasis>.
193          </para>
194          <para>
195            Local settings in the raw data
196            tables, <filename>/path/to/base/www/WEB-INF/classes/raw-data-types.xml</filename>,
197            may need to be transferred.
198          </para>
199        </listitem>
200      </varlistentry>
201
202      <varlistentry>
203        <term>Updating database schema</term>
204        <listitem>
205          <para>
206            It is recommended that you also perform an update of your
207            database schema.  Running the update scripts are not
208            always necessary when upgrading BASE, but the running the
209            update scripts are safe even in cases when there is no
210            need to run them. Change directory
211            to <filename
212            class="directory">/path/to/base/bin/</filename> and issue
213<programlisting>sh ./updatedb.sh <emphasis>base_root_password</emphasis>
214sh ./updateindexes.sh <emphasis>base_root_password</emphasis></programlisting>
215            where <emphasis>base_root_password</emphasis> is the
216            password for the root user account within the BASE
217            application.
218          </para>
219        </listitem>
220      </varlistentry>
221
222      <varlistentry>
223        <term>Remove tomcat cache</term>
224        <listitem>
225          <para>
226            As tomcat user, remove cached files and directories. Do
227            something like
228<programlisting>cd /usr/share/apache-tomcat-5.5.15/
229rm -rf work/Catalina</programlisting>
230          </para>
231        </listitem>
232      </varlistentry>
233
234      <varlistentry>
235        <term>Start tomcat</term>
236        <listitem>
237          <para>
238            Start the tomcat server: <command>sudo
239              /etc/init.d/tomcat5.5 start</command>
240          </para>
241        </listitem>
242      </varlistentry>
243
244    </variablelist>
245
246    <para>
247      Done! Upgrade of BASE is finished.
248    </para>
249
250  </sect1>      <!-- Upgrade instructions -->
251
252
253  <sect1 id="installation_upgrade.jobagents">
254    <title>Installing job agents</title>
255
256    <para>
257      It is important to understand that the BASE application can be
258      spread on to several computers. The main BASE application is
259      serving HTTP requests, the underlying database engine is
260      providing storage and persistence of data, and job agents can be
261      installed on computers that will serve the BASE installation
262      with computing power and perform analysis and run plug-in. In a
263      straight forward setup one computer provides all services needed
264      for running BASE. From this starting point it is easy to add
265      computers to shares load from the BASE server by installing job
266      agents on these additional computers.
267    </para>
268
269    <para>
270      A job agent is a program running on a computer regularly
271      checking the BASE job queue for jobs awaiting execution. When
272      the job agent finds a job that it is enabled to execute, it
273      loads the plugin and executes it. Job agents will in this way
274      free up resources on the BASE application server, and thus allow
275      the BASE server to concentrate on serving web pages. Job agents
276      are optional and must be installed and setup
277      separately. However, BASE is prepared for job agent setup and to
278      utilize the agents, but the agent are not required.
279    </para>
280
281    <para>
282      A job agent supports many configuration options that are not
283      supported by the internal job queue. For example, you can
284      <itemizedlist>
285        <listitem>
286          <para>
287            Specify exactly which plugins each job agent should be
288            able to execute.
289          </para>
290        </listitem>
291        <listitem>
292          <para>
293            Give some plugins higher priority than other plugins.
294          </para>
295        </listitem>
296        <listitem>
297          <para>
298            Specify which users/groups/projects should be able to use
299            a specific job agent.
300          </para>
301        </listitem>
302        <listitem>
303          <para>
304            Override memory settings and more for each plugin.
305          </para>
306        </listitem>
307        <listitem>
308          <para>
309            Execute plugins in separate processes. Thus, a misbehaving
310            plugin cannot bring the main application server down.
311          </para>
312        </listitem>
313        <listitem>
314          <para>
315            Add more computers with job agents as needed.
316          </para>
317        </listitem>
318      </itemizedlist>
319      All these options make it possible to create a very flexible
320      setup. For example one job agent can be assigned for importing
321      data only, another job agent can be assigned for running
322      analysis plugins for specific project only, and a third may be a
323      catch-all job agent that performs all low-priority jobs.
324    </para>
325
326    <sect2 id="installation_upgrade.jobagents.serverside">
327      <title>BASE application server side setup</title>
328      <para>
329        <variablelist>
330          <varlistentry>
331            <term>Disable the internal job queue</term>
332            <listitem>
333              <para>
334                It is not recommended to use the internal job queue
335                when job agents are used. The
336                setting <command>jobqueue.internal.enabled</command>
337                should be changed to <command>false</command> for the
338                BASE server. This setting is found in
339                the <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
340                file. The changes will not take effect until the
341                application server is restarted.
342              </para>
343            </listitem>
344          </varlistentry>
345          <varlistentry id="installation_upgrade.jobagent.user_account">
346            <term>Enable the job agent user account</term>
347            <listitem>
348              <para>
349                During installation of BASE a user account is created
350                for the job agent. This account is used by the job
351                agents to log on to BASE. The account is disabled by
352                default and must be enabled. Enable the account and
353                set a password. This password is set in the
354                <filename>jobagent.properties</filename> file, see
355                item
356                <xref linkend="installation_upgrade.jobagent.client.properties"/>
357                below.
358              </para>
359            </listitem>
360          </varlistentry>
361        </variablelist>
362      </para>
363    </sect2>
364
365    <sect2 id="installation_upgrade.jobagents.database">
366      <title>Database server setup</title>
367      <para>
368        <variablelist>
369          <varlistentry id="installation_upgrade.jobagent.database">
370            <term>Create a user account on the database</term>
371            <listitem>
372              <para>
373                This is the similar to granting database access for
374                the BASE server user in the in the regular BASE
375                installation, cf.
376                <xref
377                linkend="installation_upgrade.installation.database"/>.
378                You must create an account in the database that is
379                allowed to connect from the job agent server. MySQL
380                example:
381<programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password';
382GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting>
383
384                Replace <command>job.agent.host</command> with the
385                host name of the server that is going to run the job
386                agent. You should also set password. This password is
387                used in item
388                <xref linkend="installation_upgrade.jobagent.client.config"/>
389                below in job agent server setup. You can use the same
390                database user and password as in the regular database
391                setup.
392              </para>
393            </listitem>
394          </varlistentry>
395        </variablelist>
396      </para>
397    </sect2>
398
399    <sect2 id="installation_upgrade.jobagents.client">
400      <title>Job agent client setup</title>
401      <para>
402        <variablelist>
403          <varlistentry>
404            <term>Download and unpack a regular BASE 2 distribution</term>
405            <listitem>
406              <para>
407                You <emphasis>must</emphasis> use the same version on
408                the web server and all job agents. You find the
409                downloads at
410                <ulink
411                url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink>
412              </para>
413            </listitem>
414          </varlistentry>
415          <varlistentry id="installation_upgrade.jobagent.client.config">
416            <term>Edit the <filename>base.config</filename> file</term>
417            <listitem>
418              <para>
419                The <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
420                file must be configured as in regular BASE
421                installation, cf.
422                <xref
423                linkend="installation_upgrade.installation.configuration"/>,
424                to use the same database as the web server
425                application. The most important settings are
426                <itemizedlist>
427                  <listitem>
428                    <para>
429                      <command>db.username</command>: The database
430                      user you created in item
431                      <xref
432                      linkend="installation_upgrade.jobagent.database"/>
433                      above.
434                    </para>
435                  </listitem>
436                  <listitem>
437                    <para>
438                      <command>db.password</command>: The password for
439                      the user.
440                    </para>
441                  </listitem>
442                  <listitem>
443                    <para>
444                      <command>db.url</command>: The connection url to
445                      the database.
446                    </para>
447                  </listitem>
448                  <listitem>
449                    <para>
450                      <command>userfile</command>: The path to the
451                      directory where user files are located. This
452                      directory must be accessible from all job
453                      agents, i.e., by nfs or other file system
454                      sharing method.
455                    </para>
456                  </listitem>
457                </itemizedlist>
458                See the <xref linkend="appendix.base.config"/> for
459                more information about the settings in
460                the <filename>base.config</filename> file.
461              </para>
462            </listitem>
463          </varlistentry>
464          <varlistentry id="installation_upgrade.jobagent.client.properties">
465            <term>Edit
466            the <filename>jobagent.properties</filename> file</term>
467            <listitem>
468              <para>
469                The <filename>/path/to/base/www/WEB-INF/classes/jobagent.properties</filename>
470                file contains settings for the job agent. The most
471                important ones to specify value for are
472                <itemizedlist>
473                  <listitem>
474                    <para>
475                      <command>agent.password</command>: The password
476                      you set for the job agent user account in item
477                      <xref
478                      linkend="installation_upgrade.jobagent.user_account"/>
479                      above.
480                    </para>
481                  </listitem>
482                  <listitem>
483                    <para>
484                      <command>agent.id</command>: An ID that must be
485                      unique for each job agent accessing the BASE application.
486                    </para>
487                  </listitem>
488                  <listitem>
489                    <para>
490                      <command>agent.remotecontrol</command>: The
491                      name/ip address of the web server if you want it
492                      to be able to display info about running
493                      jobs. The job agent will only allow connections
494                      from computers specified in this setting.
495                    </para>
496                  </listitem>
497                </itemizedlist>
498              </para>
499              <para>
500                The <filename>jobagent.properties</filename> file
501                contains many more configuration options. See
502                the <xref linkend="appendix.jobagent.properties"/> for
503                more information.
504              </para>
505            </listitem>
506          </varlistentry>
507          <varlistentry>
508            <term>Register the job agent</term>
509            <listitem>
510              <para>
511                From the <filename>bin</filename> directory, register
512                the job agent with
513                <programlisting>./jobagent.sh register</programlisting>
514              </para>
515            </listitem>
516          </varlistentry>
517          <varlistentry>
518            <term>Start the job agent</term>
519            <listitem>
520              <para>
521                From the <filename>bin</filename> directory, start the
522                job agent with
523                <programlisting>./jobagent.sh start &amp;</programlisting>
524              </para>
525              <para>
526                See the <xref linkend="appendix.jobagent.sh"/>
527                reference for more information about what you can do
528                with the job agent command line interface.
529              </para>
530            </listitem>
531          </varlistentry>
532        </variablelist>
533      </para>
534    </sect2>
535
536    <sect2 id="installation_upgrade.jobagents.configuration">
537      <title>Configuring the job agent</title>
538      <para>
539        Before the job agent starts executing jobs for you it must be
540        configured. The configuration is done through the BASE web
541        interface.
542        <variablelist>
543          <varlistentry>
544            <term>Configure the plugins the job agent should handle</term>
545            <listitem>
546              <para>
547                <itemizedlist>
548                  <listitem>
549                    <para>
550                      Go to the
551                      <menuchoice>
552                        <guimenu>Administrate</guimenu>
553                        <guisubmenu>Plugins</guisubmenu>
554                        <guimenuitem>Job agents</guimenuitem>
555                      </menuchoice> menu.
556                    </para>
557                  </listitem>
558                  <listitem>
559                    <para>
560                      Select the job agent and click on the &gbEdit;
561                      button.
562                    </para>
563                  </listitem>
564                  <listitem>
565                    <para>
566                      On the <guilabel>Plugins</guilabel> tab you can
567                      specify which plugins the job agent should
568                      handle. Note that if you have installed external
569                      plugins on the web server, those plugins must be
570                      installed on the job agent as well. It is
571                      possible to specify different paths to the JAR
572                      file for each job agent.
573                    </para>
574                  </listitem>
575                </itemizedlist>
576              </para>
577            </listitem>
578          </varlistentry>
579          <varlistentry>
580            <term>Grant users access to the job agent</term>
581            <listitem>
582              <para>
583                Use the regular <guilabel>Share</guilabel>
584                functionality to specify which users/groups/projects
585                should be able to use the job agent. You must give
586                them at least <command>USE</command> permission.
587              </para>
588            </listitem>
589          </varlistentry>
590        </variablelist>
591      </para>
592    </sect2>
593
594  </sect1>      <!-- job agent setup -->
595
596
597  <sect1 id="installation_upgrade.installation">
598    <title>Installation instructions</title>
599
600    <variablelist>
601
602      <varlistentry>
603        <term>Java</term>
604        <listitem>
605          <para>
606            Download and install Java SDK 1.5, available from
607            <ulink url="http://java.sun.com/" />. Make sure that you
608            download the JDK version (<emphasis>not</emphasis> the JRE
609            version). <command>Java 6 is currently not
610            supported</command> (this will change starting with
611            BASE version 2.5 whereafter only Java 6 will be supported).
612          </para>
613        </listitem>
614      </varlistentry>
615
616      <varlistentry>
617        <term>Tomcat</term>
618        <listitem>
619          <para>
620            Download and install tomcat 5.5.16 or later, available
621            from <ulink
622            url="http://jakarta.apache.org/tomcat/" />
623            <important>
624              You MUST make sure that Tomcat uses the SERVER mode of
625              the Java run time engine
626              (see <ulink
627              url="http://lev.thep.lu.se/trac/base/ticket/99">ticket:99</ulink>).
628            </important>
629            On Linux you do this by setting the environment variable:
630            <code>CATALINA_OPTS</code> to <code>-server</code>. It is
631            also a good idea to specify the maximum allowed memory to
632            use: <code>-server -Xmx500m</code> sets it to 500
633            megabytes. Basically add the next line close to the top of
634            the <filename>catalina.sh</filename> script that comes
635            with tomcat
636            (directory <filename
637            class="directory">bin</filename>):
638<programlisting>CATALINA_OPTS="-server -Xmx500m"</programlisting>
639          </para>
640          <para>
641            For more information about Tomcat options see
642            <ulink url="http://www.chemaxon.com/jchem/doc/admin/tomcat.html" />.
643          </para>
644        </listitem>
645      </varlistentry>
646
647      <varlistentry>
648        <term>Set up SQL database</term>
649        <listitem>
650          <para>
651            BASE 2
652            utilize <ulink
653            url="http://www.hibernate.org/">Hibernate</ulink> for
654            object persistence to a relational database. Hibernate
655            supports many database engines, but so far we only work
656            with <ulink url="http://www.mysql.com">MySQL</ulink>
657            and <ulink
658            url="http://www.postgresql.org/">PostgreSQL</ulink>.
659          </para>
660
661          <variablelist>
662            <varlistentry>
663              <term>MySQL</term>
664              <listitem>
665                <para>
666                  Download and install MySQL (tested with version
667                  5.0), available from
668                  <ulink url="http://www.mysql.com/" />. You need to
669                  be able to connect to the server over TCP, so
670                  the <emphasis>skip-networking</emphasis> option
671                  must <command>not</command> be used. The InnoDB
672                  table engine is also needed, so do not disable them
673                  (not that you would) but you may want to tune the
674                  InnoDB behaviour before creating BASE
675                  databases. BASE comes pre-configured for MySQL so
676                  there is no need to change database settings in the
677                  BASE configuration files.
678                </para>
679              </listitem>
680            </varlistentry>
681            <varlistentry>
682              <term>PostgreSQL</term>
683              <listitem>
684                <para>
685                  PostgreSQL 8.0 seems to be working very well with
686                  BASE and Hibernate. Download and install PostgreSQL,
687                  available from
688                  <ulink url="http://www.postgresql.org/" />. you must
689                  edit
690                  your <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
691                  file. Uncomment the settings for Postgres and
692                  comment out the settings for MySQL.
693                </para>
694              </listitem>
695            </varlistentry>
696          </variablelist>
697
698        </listitem>
699      </varlistentry>
700
701      <varlistentry>
702        <term>BASE (download and unpacking)</term>
703        <listitem>
704          <para>
705            <ulink
706            url="http://base.thep.lu.se/wiki/DownloadPage">Download
707            BASE</ulink> and unpack the downloaded file,
708            i.e. <command>tar zxpf base-...tar.gz</command>. If you
709            prefer to have the bleeding edge version of BASE, perform
710            a checkout of the source from the subversion repository
711            (subversion checkout instructions at
712            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
713            trac site</ulink>).
714          </para>
715          <para>
716            If you choose to download the binary package, skip to the
717            next item. The rest of us, read on and compile BASE 2. If
718            you downloaded a source distribution, unpack the
719            downloaded file <command>tar zxpf
720            base-...src.tar.gz</command>, or you may have performed a
721            subversion checkout.  Change to the 'root' base2
722            directory, and issue <command>ant
723            package.bin</command>. This will create a binary package
724            in the base2 'root' directory. Unpack this new package
725            (outside of the source file hierarchy), and from now on
726            the instructions are the same irrespective where you got
727            the binary package.
728          </para>
729          <para>
730            <emphasis>This section is intended for advanced users and
731              programmers only. In cases when you want to change the
732              BASE code and try out personalized features it may be
733              advantageous to run the tweaked BASE server against the
734              development tree. Instructions on how to accomplish this
735              is available in the
736              <ulink
737              url="http://base.thep.lu.se/chrome/site/doc/development/build.html">building
738              BASE document</ulink>. When you return back after
739              compiling in the subversion tree you can follow the
740              instruction here (with obvious changes to
741              paths).</emphasis>
742          </para>
743        </listitem>
744      </varlistentry>
745
746      <varlistentry id="installation_upgrade.installation.database">
747        <term>BASE (database engine)</term>
748        <listitem>
749          <para>
750            Instructions for MySQL and PostgreSQL are available
751            below. The database names (base2 and base2dynamic is used
752            here), the <emphasis>db_user</emphasis>, and
753            the <emphasis>db_password</emphasis> can be changed during
754            the creation of the databases. It is recommended to change
755            the <emphasis>db_password</emphasis>, the other changes
756            can be made if desired. The database names,
757            the <emphasis>db_user</emphasis>, and
758            the <emphasis>db_password</emphasis> are needed in a later
759            step below when configuring BASE.
760          </para>
761          <note>
762            Note that the <emphasis>db_user</emphasis> name
763            and <emphasis>db_password</emphasis> set here is used
764            internally by BASE in communication with the database and
765            is never used to log on to the BASE application.
766          </note>
767          <variablelist>
768            <varlistentry>
769              <term>MySQL</term>
770              <listitem>
771                <para>
772                  Create a new database for BASE, and add a
773                  <emphasis>db_user</emphasis> with at least
774                  <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
775                  <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
776                  <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
777                  <emphasis>INDEX</emphasis>,
778                  and <emphasis>ALTER</emphasis> permission for the
779                  new database. To do this, connect to your MySQL
780                  server and issue the next lines:
781<programlisting>CREATE DATABASE base2;
782CREATE DATABASE base2dynamic;
783GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
784GRANT ALL ON base2dynamic.* TO db_user@localhost;</programlisting>
785                </para>
786                <para>
787                  The <filename>/path/to/base/misc/sql/createdb.mysql.sql</filename>
788                  file contains the above statements and can be used
789                  by the <filename>mysql</filename> command-line tool
790                  (remember to edit
791                  the <emphasis>db_user</emphasis>,
792                  <emphasis>db_password</emphasis>,
793                  and the database names in the script file before
794                  executing the command): <command>mysql -uroot -p
795                  &lt; ./misc/sql/createdb.mysql.sql</command>. The
796                  header in the script file contains further
797                  information about the script.
798                </para>
799              </listitem>
800            </varlistentry>
801            <varlistentry>
802              <term>PostgreSQL</term>
803              <listitem>
804                <para>
805                  Create a new database for BASE, and add a
806                  <emphasis>db_user</emphasis> with the proper
807                  privileges. To do this, log in as your PostgreSQL
808                  user and issue these lines (omit comments):
809<programlisting>createuser db_user -P
810  # this will prompt for an password for the new user, and issue two
811  # more question that should be answered with character 'n' for no.
812createdb --owner db_user --encoding UNICODE base2
813psql base2
814  # this will start the psql command line tool. Issue the next line
815  # within the tool and quit with a '\q'.
816CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting>
817                  The <filename>/path/to/base/misc/sql/createdb.postgresql.sql</filename>
818                  file contains the above statements and can be used
819                  by the <filename>psql</filename> command-line tool:
820                  <command>psql -f ./misc/sql/createdb.posgres.sql
821                    template1</command> The header in the script file
822                  contains further information about the script.
823                </para>
824              </listitem>
825            </varlistentry>
826          </variablelist>
827        </listitem>
828      </varlistentry>
829
830      <varlistentry>
831        <term>BASE (file storage setup)</term>
832        <listitem>
833          <para>
834            An area for file storage must be setup. Create an empty
835            directory in a proper location in your file system, and
836            set the owner to be the same as the one that the tomcat
837            server will be running as. Remember this location for
838            later use.
839          </para>
840        </listitem>
841      </varlistentry>
842
843      <varlistentry id="installation_upgrade.installation.configuration">
844        <term>BASE (configuration)</term>
845        <listitem>
846          <para>
847            Basic BASE configuration is done in
848            <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>:
849            <itemizedlist>
850              <listitem>
851                Uncomment the database engine section that match your setup.
852              </listitem>
853              <listitem>
854                Modify the <emphasis>db.url</emphasis>,
855                <emphasis>db.dynamic.catalog</emphasis>,
856                <emphasis>db.username</emphasis>,
857                and <emphasis>db.password</emphasis> settings to match
858                your choice above. (<emphasis>database host and
859                database name (e.g. base2)</emphasis>,
860                <emphasis>e.g. base2dynamic</emphasis>,
861                <emphasis>db_user</emphasis>, and
862                <emphasis>db_password</emphasis>, respectively.)
863              </listitem>
864              <listitem>
865                Modify the <emphasis>userfiles</emphasis> setting to
866                match your choice above.
867              </listitem>
868            </itemizedlist>
869            See the <xref linkend="appendix.base.config"/> for more
870            information about the settings in
871            the <filename>base.config</filename> file.
872          </para>
873          <para>
874            <emphasis>Optional but recommended.</emphasis> You may want
875            to modify extended properties to fit your needs. Extended
876            properties are defined in
877            <filename>/path/to/base/www/WEB-INF/classes/extended-properties.xml</filename>.
878            There is an administrator <ulink
879            url="http://base.thep.lu.se/chrome/site/doc/admin/extended-properties.html">document
880              discussing extended properties</ulink> available.
881          </para>
882        </listitem>
883      </varlistentry>
884
885      <varlistentry>
886        <term>BASE (database initialization)</term>
887        <listitem>
888          <para>
889            Change directory to
890            <filename class="directory">/path/to/base/bin</filename>
891            and run <filename>initdb.sh</filename> as
892<programlisting>./initdb.sh base_root_password</programlisting>
893            <important>
894            The <emphasis>base_root_password</emphasis> you use here
895            is given to the BASE web application
896            user <emphasis>root</emphasis>. There is no supported way
897            to change the <emphasis>root</emphasis> account name.
898            </important>
899            If the initialisation script fail, it is most probably a
900            problem related to the underlying database. Make sure that
901            the database accepts network connection and make sure that
902            <emphasis>db_user</emphasis> has proper credentials.
903          </para>
904        </listitem>
905      </varlistentry>
906
907      <varlistentry>
908        <term>BASE and tomcat</term>
909        <listitem>
910          <para>
911            Either move the <filename
912            class="directory">/path/to/base/www</filename> directory
913            to the tomcat <filename class="directory">webapps</filename>
914            directory or create a symbolic link from the tomcat
915            <filename class="directory">webapps</filename> directory to
916            the <filename class="directory">/path/to/base/www</filename>
917            directory
918<programlisting>cd /path/to/tomcat/webapps
919ln -s /path_to_base/www base2</programlisting>
920            Start/restart tomcat, and try http://hostname:8080/base2
921            (change <emphasis>hostname</emphasis> to your hostname) in
922            your favourite browser. BASE log-in page should appear
923            after a few seconds.
924          </para>
925        </listitem>
926      </varlistentry>
927
928      <varlistentry>
929        <term>BASE, apache, and apache/tomcat connector</term>
930        <listitem>
931          <para>
932            <emphasis>This step is optional</emphasis>.
933          </para>
934          <para>
935            If you want run the tomcat server through the apache web
936            server, you need to install the apache version 2 web
937            server, available
938            from <ulink
939            url="http://www.apache.org/">http://www.apache.org/</ulink>,
940            and a apache-tomcat connector, available
941            from <ulink
942            url="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</ulink>.
943            So, we got you there;-) To be honest, this step is not
944            really well documented since we previously used SuSE 9.3
945            on our demo/test server, and apache/tomcat/mod_jk comes
946            pre-installed. The current server does not use the
947            apache/tomcat connector. What you need to do is something
948            like this
949            <itemizedlist>
950              <listitem>
951                Get that tomcat server running in stand-alone
952                mode.
953              </listitem>
954              <listitem>
955                Get the apache 2 server running.
956              </listitem>
957              <listitem>
958                Install mod_jk. Note, different version are used for
959                apache 1.3 and 2. In SuSE 9.3 this step is done by
960                installing <filename>mod_jk-ap20</filename>.
961              </listitem>
962              <listitem>
963                Create a <filename>workers.properties</filename> file
964                in the
965                tomcat <filename class="directory">base</filename>
966                directory (commonly copied from a template).
967              </listitem>
968              <listitem>
969                Create a <filename>jk.conf</filename> file in the
970                apache <filename class="directory">conf</filename>
971                directory (commonly copied from a template), and make
972                sure that <emphasis>jk</emphasis> is added to the
973                modules to be loaded when apache starts.
974              </listitem>
975              <listitem>
976                In <filename>jk.conf</filename> add the lines below
977                and change paths appropriately.
978<programlisting># The following lines makes apache aware of the location of
979# the /base2 context
980Alias /base2 "/srv/www/tomcat5/base/webapps/base2"
981&lt;Directory "/srv/www/tomcat5/base/webapps/base2"&gt;
982Options Indexes FollowSymLinks
983allow from all
984&lt;/Directory&gt;
985# The following lines mounts all base2 jsp files to tomcat
986JkMount /base2 ajp13
987JkMount /base2/* ajp13
988# The following lines prohibits users from directly accessing WEB-INF
989&lt;Location "/base2/WEB-INF/"&gt;
990AllowOverride None
991deny from all
992&lt;/Location&gt;</programlisting>
993              </listitem>
994            </itemizedlist>
995            You must restart the apache and the tomcat server after above steps.
996          </para>
997        </listitem>
998      </varlistentry>
999
1000      <varlistentry>
1001        <term>Setup done!</term>
1002        <listitem>
1003          <para>
1004            Happy BASEing. Now you can log on to your BASE 2 server as
1005            user <emphasis>root</emphasis> (use
1006            the <emphasis>base_root_password</emphasis> from the
1007            database initialization step above). You should begin with
1008            creating a couple user accounts, for more information on
1009            how to create user accounts please refer to
1010            <xref linkend="user_administration"/>.
1011          </para>
1012          <para>
1013            If you are planning to perform a migration of data from
1014            BASE 1.2.x please perform the steps in
1015            <xref linkend="installation_upgrade.migration"/> before
1016            doing anything else with your new BASE installation.
1017          </para>
1018        </listitem>
1019      </varlistentry>
1020
1021    </variablelist>
1022
1023  </sect1>      <!-- Installation instructions -->
1024
1025
1026  <sect1 id="installation_upgrade.migration">
1027    <title>Migration instructions</title>
1028
1029    <caution>
1030      <title>The disclaimer section</title>
1031      <para>
1032        We have made extensive testing of the migration from BASE1.2
1033        to BASE2. To our knowledge the migration works but we cannot
1034        guarantee perfect functionality. The migration tool is
1035        supplied as is and usage is done at your risk. We are
1036        committed to solve migration problems at the level of
1037        transferring data from BASE 1.2 to 2.2.x, but cannot resolve
1038        data loss issues in a running BASE 2 server due to imperfect
1039        migration. When you start the migration tool you are required
1040        to pass parameter <emphasis>"disclaimer_understood"</emphasis>
1041        to the <filename>migrate_from_1.2.sh</filename>
1042        script. Remember to check that the migration performed well
1043        before you decide to delete your 1.2 installation.
1044      </para>
1045      <para>
1046        Migration from the latest BASE 1.2.x release to the latest is
1047        supported.
1048      </para>
1049    </caution>
1050
1051    <para>
1052      Verify that your BASE 2 installation is up and running before
1053      attempting migration. Preferably try to log in using the root
1054      user through the web interface.
1055    </para>
1056
1057    <para>
1058      Make sure your BASE 1.2 runs with the latest
1059      (<emphasis>pristine</emphasis>) schema
1060      version, <emphasis>i.e.,</emphasis> the migration will only
1061      support an unmodified BASE 1.2 installation. If you have an out
1062      of date schema version, please upgrade to the latest schema
1063      using BASE 1.2 tools before migrating. If you have made local
1064      changes to the BASE 1.2 schema you need to patch the BASE 2
1065      schema as well as make proper changes to the migration program.
1066    </para>
1067
1068    <para>
1069      The behaviour of migration is controlled
1070      through <filename>migration.properties</filename> file (see
1071      <xref linkend="appendix.migrate.properties"/>), but you should
1072      know what you do when you change parameters in this file.
1073    </para>
1074
1075    <para>
1076      Migration can be restarted in one specific case only; If the
1077      migration fails during the RawBioAssaysData transfer simply
1078      restart the migration and the script will ask you to verify that
1079      a restart should be attempted. For all other failure points the
1080      migration has to be restarted with an empty database.
1081    </para>
1082
1083    <para>
1084      Migration is performed with the following steps:
1085      <orderedlist>
1086
1087        <listitem>
1088          <para>
1089            To transfer files from BASE 1.2 (default migration
1090            behaviour), you must have file system access to BASE 1.2
1091            files, <emphasis>i.e.,</emphasis> the <filename
1092            class="directory">/path/to/base1.2/data</filename>
1093            directory containing directories
1094            <filename class="directory">rawdata</filename>,
1095            <filename class="directory">uploads</filename>,
1096            <filename class="directory">protocols</filename>, ...
1097          </para>
1098        </listitem>
1099
1100        <listitem>
1101          <para>
1102            Change settings in the file
1103            <filename>/path/to/base/dist/www/WEB-INF/classes/migrate.properties</filename>.
1104            The available options are commented:
1105            <itemizedlist>
1106              <listitem>
1107                <para>
1108                  Modify <emphasis>db1.*</emphasis> parameters to
1109                  match your BASE 1.2 installation.
1110                </para>
1111              </listitem>
1112              <listitem>
1113                <para>
1114                  Set <emphasis>userfiles</emphasis> (note, this is
1115                  not the same parameter as
1116                  in <filename>base.config</filename>) to point to the
1117                  directory containing the BASE 1.2 files (defined in a
1118                  previous step above).
1119                </para>
1120              </listitem>
1121              <listitem>
1122                <para>
1123                  Set the <emphasis>pluginDir</emphasis> to point to
1124                  the directory where your BASE 1.2 plug-ins are
1125                  installed. The default is
1126                  <filename
1127                  class="directory">/usr/local/base/plugins</filename>.
1128                </para>
1129              </listitem>
1130              <listitem>
1131                <para>
1132                  Modify <emphasis>root.password</emphasis>.
1133                </para>
1134              </listitem>
1135              <listitem>
1136                <para>
1137                  Change the <emphasis>deletefiles</emphasis> setting
1138                  wisely. If you
1139                  set <emphasis>deletefiles=yes</emphasis> all BASE
1140                  1.2 files will be physically removed when copied to
1141                  BASE 2. Leave this options
1142                  as <emphasis>deletefiles=no</emphasis> unless you
1143                  are absolutely sure of what you are doing.
1144                </para>
1145              </listitem>
1146            </itemizedlist>
1147          </para>
1148        </listitem>
1149
1150        <listitem>
1151          <para>
1152            Run migration utility:
1153<programlisting>cd /path_to_base/dist/bin
1154./migrate_from_1.2.sh</programlisting>
1155          </para>
1156          <para>
1157            If the migration fails during the RawBioAssaysData
1158            transfer you can restart the migration at the point of
1159            failure. Simply restart the migration and the script will
1160            ask you to verify that a restart should be attempted. For
1161            all other failure points the migration has to be restarted
1162            with an empty database.
1163          </para>
1164        </listitem>
1165
1166        <listitem>
1167          <para>
1168            Migration done! Happy BASEing.
1169          </para>
1170        </listitem>
1171
1172      </orderedlist>
1173
1174    </para>
1175
1176  </sect1>      <!-- Migration instructions -->
1177
1178</chapter>
Note: See TracBrowser for help on using the repository browser.