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

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

Fixes #615.

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