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

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

Addresses #516. Migration instructions done.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 28.0 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 3355 2007-05-21 14:40:49Z jari $
7
8  Copyright (C) Authors contributing to this file.
9
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 2
16  of the License, or (at your option) any later version.
17
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<chapter id="installation_upgrade">
30  <?dbhtml dir="installation_upgrade"?>
31
32  <title>Installation, migration, and upgrade instructions</title>
33
34  <note>
35    These instructions apply only to the BASE release which this
36    document is a part of.
37  </note>
38
39  <para>
40    This chapter is divided into three parts. First, the process of
41    upgrading a BASE 2 server is described. It is assumed that there
42    is a running server. Then, the first time installation
43    instructions follows, and the chapter is concluded with
44    information on how to migrate data from a BASE 1.2.17 server to a
45    BASE 2 server.
46  </para>
47
48  <para>
49    The first time installation is expected to be performed only once,
50    and optionally followed by a migration. The migration can only be
51    done to a pristine (empty) BASE 2 server, and migration from
52    several BASE 1 installations to one BASE 2 server is not
53    supported.
54  </para>
55
56  <para>
57    The instructions here assume
58    that <ulink url="http://tomcat.apache.org/">tomcat</ulink> is used
59    on the server side. Other servlet engines may work but we only
60    test tomcat.
61  </para>
62
63
64  <sect1 id="installation_upgrade.upgrade">
65    <title>Upgrade instructions</title>
66
67    <important>
68      <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
162                  to <ulink
163                  url="http://base.thep.lu.se/chrome/site/doc/development/build.html">the
164                  building BASE document</ulink> 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="direcotry">/path/to/base/bin/</filename> and issue
213            <programlisting>
214sh ./updatedb.sh <emphasis>base_root_password</emphasis>
215sh ./updateindexes.sh <emphasis>base_root_password</emphasis>
216</programlisting>
217            where <emphasis>base_root_password</emphasis> is the
218            password for the root user account within the BASE
219            application.
220          </para>
221        </listitem>
222      </varlistentry>
223
224      <varlistentry>
225        <term>Remove tomcat cache</term>
226        <listitem>
227          <para>
228            As tomcat user, remove cached files and directories. Do
229            something like
230            <programlisting>
231cd /usr/share/apache-tomcat-5.5.15/
232rm -rf work/Catalina
233</programlisting>
234          </para>
235        </listitem>
236      </varlistentry>
237
238      <varlistentry>
239        <term>Start tomcat</term>
240        <listitem>
241          <para>
242            Start the tomcat server: <command>sudo
243              /etc/init.d/tomcat5.5 start</command>
244          </para>
245        </listitem>
246      </varlistentry>
247
248    </variablelist>
249
250    <para>
251      Done! Upgrade of BASE is finished.
252    </para>
253
254  </sect1>      <!-- Upgrade instructions -->
255
256
257  <sect1 id="installation_upgrade.installation">
258    <title>Installation instructions</title>
259
260    <variablelist>
261
262      <varlistentry>
263        <term>Java</term>
264        <listitem>
265          <para>
266            Download and install Java SDK 1.5, available from
267            <ulink url="http://java.sun.com/" />. Make sure that you
268            download the JDK version (<emphasis>not</emphasis> the JRE
269            version). <command>Java 6 is currently not
270            supported</command>.
271          </para>
272        </listitem>
273      </varlistentry>
274
275      <varlistentry>
276        <term>Tomcat</term>
277        <listitem>
278          <para>
279            Download and install tomcat 5.5.16 or later, available
280            from <ulink
281            url="http://jakarta.apache.org/tomcat/" />
282            <important>
283              You MUST make sure that Tomcat uses the SERVER mode of
284              the Java run time engine
285              (see <ulink
286              url="http://lev.thep.lu.se/trac/base/ticket/99">ticket:99</ulink>).
287            </important>
288            On Linux you do this by setting the environment variable:
289            <code>CATALINA_OPTS</code> to <code>-server</code>. It is
290            also a good idea to specify the maximum allowed memory to
291            use: <code>-server -Xmx500m</code> sets it to 500
292            megabytes. Basically add the next line close to the top of
293            the <filename>catalina.sh</filename> script that comes
294            with tomcat
295            (directory <filename
296            class="direcotry">bin</filename>): <programlisting>
297CATALINA_OPTS="-server -Xmx500m"
298</programlisting>
299          </para>
300          <para>
301            For more information about Tomcat options see
302            <ulink url="http://www.chemaxon.com/jchem/doc/admin/tomcat.html" />.
303          </para>
304        </listitem>
305      </varlistentry>
306
307      <varlistentry>
308        <term>Set up SQL database</term>
309        <listitem>
310          <para>
311            BASE 2
312            utilize <ulink
313            url="http://www.hibernate.org/">Hibernate</ulink> for
314            object persistence to a relational database. Hibernate
315            supports many database engines, but so far we only work
316            with <ulink url="http://www.mysql.com">MySQL</ulink>
317            and <ulink
318            url="http://www.postgresql.org/">PostgreSQL</ulink>.
319          </para>
320
321          <variablelist>
322            <varlistentry>
323              <term>MySQL</term>
324              <listitem>
325                <para>
326                  Download and install MySQL (tested with version
327                  5.0), available from
328                  <ulink url="http://www.mysql.com/" />. You need to
329                  be able to connect to the server over TCP, so
330                  the <emphasis>skip-networking</emphasis> option
331                  must <command>not</command> be used. The InnoDB
332                  table engine is also needed, so don't disable them
333                  (not that you would) but you may want to tune the
334                  InnoDB behaviour before creating BASE
335                  databases. BASE comes pre-configured for MySQL so
336                  there is no need to change database settings in the
337                  BASE configuration files.
338                </para>
339              </listitem>
340            </varlistentry>
341            <varlistentry>
342              <term>PostgreSQL</term>
343              <listitem>
344                <para>
345                  PostgreSQL 8.0 seems to be working very well with
346                  BASE and Hibernate. Download and install PostgreSQL,
347                  available from
348                  <ulink url="http://www.postgresql.org/" />. you must
349                  edit
350                  your <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
351                  file. Uncomment the settings for Postgres and
352                  comment out the settings for MySQL.
353                </para>
354              </listitem>
355            </varlistentry>
356          </variablelist>
357
358        </listitem>
359      </varlistentry>
360
361      <varlistentry>
362        <term>BASE (download and unpacking)</term>
363        <listitem>
364          <para>
365            <ulink
366            url="http://base.thep.lu.se/wiki/DownloadPage">Download
367            BASE</ulink> and unpack the downloaded file,
368            i.e. <command>tar zxpf base-...tar.gz</command>. If you
369            prefer to have the bleeding edge version of BASE, perform
370            a checkout of the source from the subversion repository
371            (subversion checkout instructions at
372            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
373            trac site</ulink>).
374          </para>
375          <para>
376            If you choose to download the binary package, skip to the
377            next item. The rest of us, read on and compile BASE 2. If
378            you downloaded a source distribution, unpack the
379            downloaded file <command>tar zxpf
380            base-...src.tar.gz</command>, or you may have performed a
381            subversion checkout.  Change to the 'root' base2
382            directory, and issue <command>ant
383            package.bin</command>. This will create a binary package
384            in the base2 'root' directory. Unpack this new package
385            (outside of the source file hierarchy), and from now on
386            the instructions are the same irrespective where you got
387            the binary package.
388          </para>
389          <para>
390            <emphasis>This section is intended for advanced users and
391              programmers only. In cases when you want to change the
392              BASE code and try out personalized features it may be
393              advantageous to run the tweaked BASE server against the
394              development tree. Instructions on how to accomplish this
395              is available in the
396              <ulink
397              url="http://base.thep.lu.se/chrome/site/doc/development/build.html">building
398              BASE document</ulink>. When you return back after
399              compiling in the subversion tree you can follow the
400              instruction here (with obvious changes to
401              paths).</emphasis>
402          </para>
403        </listitem>
404      </varlistentry>
405
406      <varlistentry>
407        <term>BASE (database engine)</term>
408        <listitem>
409          <para>
410            Instructions for MySQL and PostgreSQL are available
411            below. The database names (base2 and base2dynamic is used
412            here), the <emphasis>db_user</emphasis>, and
413            the <emphasis>db_password</emphasis> can be changed during
414            the creation of the databases. It is recommended to change
415            the <emphasis>db_password</emphasis>, the other changes
416            can be made if desired. The database names,
417            the <emphasis>db_user</emphasis>, and
418            the <emphasis>db_password</emphasis> are needed in a later
419            step below when configuring BASE.
420          </para>
421          <note>
422            Note that the <emphasis>db_user</emphasis> name
423            and <emphasis>db_password</emphasis> set here is used
424            internally by BASE in communication with the database and
425            is never used to log on to the BASE application.
426          </note>
427          <variablelist>
428            <varlistentry>
429              <term>MySQL</term>
430              <listitem>
431                <para>
432                  Create a new database for BASE, and add a
433                  <emphasis>db_user</emphasis> with at least
434                  <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
435                  <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
436                  <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
437                  <emphasis>INDEX</emphasis>,
438                  and <emphasis>ALTER</emphasis> permission for the
439                  new database. To do this, connect to your MySQL
440                  server and issue the next lines:
441                  <programlisting>
442CREATE DATABASE base2;
443CREATE DATABASE base2dynamic;
444GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
445GRANT ALL ON base2dynamic.* TO db_user@localhost;
446</programlisting>
447                </para>
448                <para>
449                  The <filename>/path/to/base/misc/sql/createdb.mysql.sql</filename>
450                  file contains the above statements and can be used
451                  by the <filename>mysql</filename> command-line tool
452                  (remember to edit
453                  the <emphasis>db_user</emphasis>,
454                  <emphasis>db_password</emphasis>,
455                  and the database names in the script file before
456                  executing the command): <command>mysql -uroot -p
457                  &lt; ./misc/sql/createdb.mysql.sql</command>. The
458                  header in the script file contains further
459                  information about the script.
460                </para>
461              </listitem>
462            </varlistentry>
463            <varlistentry>
464              <term>PostgreSQL</term>
465              <listitem>
466                <para>
467                  Create a new database for BASE, and add a
468                  <emphasis>db_user</emphasis> with the proper
469                  privileges. To do this, log in as your PostgreSQL
470                  user and issue these lines (omit comments):
471                  <programlisting>
472createuser db_user -P
473  # this will prompt for an password for the new user, and issue two
474  # more question that should be answered with character 'n' for no.
475createdb --owner db_user --encoding UNICODE base2
476psql base2
477  # this will start the psql command line tool. Issue the next line
478  # within the tool and quit with a '\q'.
479CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";
480</programlisting>
481                  The <filename>/path/to/base/misc/sql/createdb.postgresql.sql</filename>
482                  file contains the above statements and can be used
483                  by the <filename>psql</filename> command-line tool:
484                  <command>psql -f ./misc/sql/createdb.posgres.sql
485                    template1</command> The header in the script file
486                  contains further information about the script.
487                </para>
488              </listitem>
489            </varlistentry>
490          </variablelist>
491        </listitem>
492      </varlistentry>
493
494      <varlistentry>
495        <term>BASE (file storage setup)</term>
496        <listitem>
497          <para>
498            An area for file storage must be setup. Create an empty
499            directory in a proper location in your file system, and
500            set the owner to be the same as the one that the tomcat
501            server will be running as. Remember this location for
502            later use.
503          </para>
504        </listitem>
505      </varlistentry>
506
507      <varlistentry>
508        <term>BASE (configuration)</term>
509        <listitem>
510          <para>
511            Basic BASE configuration is done in
512            <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>:
513            <itemizedlist>
514              <listitem>
515                Uncomment the database engine section that match your setup.
516              </listitem>
517              <listitem>
518                Modify the <emphasis>db.url</emphasis>,
519                <emphasis>db.dynamic.catalog</emphasis>,
520                <emphasis>db.username</emphasis>,
521                and <emphasis>db.password</emphasis> settings to match
522                your choice above. (<emphasis>database host and
523                database name (e.g. base2)</emphasis>,
524                <emphasis>e.g. base2dynamic</emphasis>,
525                <emphasis>db_user</emphasis>, and
526                and <emphasis>db_password</emphasis>, respectively.)
527              </listitem>
528              <listitem>
529                Modify the <emphasis>userfiles</emphasis> setting to
530                match your choice above.
531              </listitem>
532            </itemizedlist>
533          </para>
534          <para>
535            <emphasis>Optional but recommended.</emphasis> You may want
536            to modify extended properties to fit your needs. Extended
537            properties are defined in
538            <filename>/path/to/base/www/WEB-INF/classes/extended-properties.xml</filename>.
539            There is an administrator <ulink
540            url="http://base.thep.lu.se/chrome/site/doc/admin/extended-properties.html">document
541              discussing extended properties</ulink> available.
542          </para>
543        </listitem>
544      </varlistentry>
545
546      <varlistentry>
547        <term>BASE (database initialization)</term>
548        <listitem>
549          <para>
550            Change directory to
551            <filename class="directory">/path/to/base/bin</filename>
552            and run <filename>initdb.sh</filename> as <programlisting>
553./initdb.sh base_root_password password
554</programlisting>
555            <important>
556            The <emphasis>base_root_password</emphasis> you use here
557            is given to the BASE web application
558            user <emphasis>root</emphasis>. There is no supported way
559            to change the <emphasis>root</emphasis> account name.
560            </important>
561            If the initialisation script fail, it is most probably a
562            problem related to the underlying database. Make sure that
563            the database accepts network connection and make sure that
564            <emphasis>db_user</emphasis> has proper credentials.
565          </para>
566        </listitem>
567      </varlistentry>
568
569      <varlistentry>
570        <term>BASE and tomcat</term>
571        <listitem>
572          <para>
573            Either move the <filename
574            class="directory">/path/to/base/www</filename> directory
575            to the tomcat <filename class="directory">webapps</filename>
576            directory or create a symbolic link from the tomcat
577            <filename class="directory">webapps</filename> directory to
578            the <filename class="directory">/path/to/base/www</filename>
579            directory <programlisting>
580cd /path/to/tomcat/webapps
581ln -s /path_to_base/www base2
582</programlisting>
583            Start/restart tomcat, and try http://hostname:8080/base2
584            (change <emphasis>hostname</emphasis> to your hostname) in
585            your favourite browser. BASE log-in page should appear
586            after a few seconds.
587          </para>
588        </listitem>
589      </varlistentry>
590
591      <varlistentry>
592        <term>BASE, apache, and apache/tomcat connector</term>
593        <listitem>
594          <para>
595            <emphasis>This step is optional</emphasis>.
596          </para>
597          <para>
598            If you want run the tomcat server through the apache web
599            server, you need to install the apache version 2 web
600            server, available
601            from <ulink
602            url="http://www.apache.org/">http://www.apache.org/</ulink>,
603            and a apache-tomcat connector, available
604            from <ulink
605            url="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</ulink>.
606            So, we got you there;-) To be honest, this step is not
607            really well documented since we previously used SuSE 9.3
608            on our demo/test server, and apache/tomcat/mod_jk comes
609            pre-installed. The current server does not use the
610            apache/tomcat connector. What you need to do is something
611            like this
612            <itemizedlist>
613              <listitem>
614                Get that tomcat server running in stand-alone
615                mode.
616              </listitem>
617              <listitem>
618                Get the apache 2 server running.
619              </listitem>
620              <listitem>
621                Install mod_jk. Note, different version are used for
622                apache 1.3 and 2. In SuSE 9.3 this step is done by
623                installing <filename>mod_jk-ap20</filename>.
624              </listitem>
625              <listitem>
626                Create a <filename>workers.properties</filename> file
627                in the
628                tomcat <filename class="directory">base</filename>
629                directory (commonly copied from a template).
630              </listitem>
631              <listitem>
632                Create a <filename>jk.conf</filename> file in the
633                apache <filename class="directory">conf</filename>
634                directory (commonly copied from a template), and make
635                sure that <emphasis>jk</emphasis> is added to the
636                modules to be loaded when apache starts.
637              </listitem>
638              <listitem>
639                In <filename>jk.conf</filename> add the lines below
640                and change paths appropriately. <programlisting>
641# The following lines makes apache aware of the location of
642# the /base2 context
643Alias /base2 "/srv/www/tomcat5/base/webapps/base2"
644&lt;Directory "/srv/www/tomcat5/base/webapps/base2"&gt;
645Options Indexes FollowSymLinks
646allow from all
647&lt;/Directory&gt;
648# The following lines mounts all base2 jsp files to tomcat
649JkMount /base2 ajp13
650JkMount /base2/* ajp13
651# The following lines prohibits users from directly accessing WEB-INF
652&lt;Location "/base2/WEB-INF/"&gt;
653AllowOverride None
654deny from all
655&lt;/Location&gt;
656</programlisting>
657              </listitem>
658            </itemizedlist>
659            You must restart the apache and the tomcat server after above steps.
660          </para>
661        </listitem>
662      </varlistentry>
663
664      <varlistentry>
665        <term>Setup done!</term>
666        <listitem>
667          <para>
668            Happy BASEing. Now you can log on to your BASE 2 server as
669            user <emphasis>root</emphasis> (use
670            the <emphasis>base_root_password</emphasis> from the
671            database initialization step above). You should begin with
672            creating a couple user accounts, for more information on
673            how to create user accounts please refer to
674            <xref linkend="user_administration"/>.
675          </para>
676        </listitem>
677      </varlistentry>
678
679    </variablelist>
680
681  </sect1>      <!-- Installation instructions -->
682
683
684  <sect1 id="installation_upgrade.migration">
685    <title>Migration instructions</title>
686
687    <caution>
688      <title>The disclaimer section</title>
689      <para>
690        We have made extensive testing of the migration from BASE1.2
691        to BASE2. To our knowledge the migration works but we cannot
692        guarantee perfect functionality. The migration tool is
693        supplied as is and usage is done at your risk. We are
694        committed to solve migration problems at the level of
695        transferring data from BASE 1.2 to 2.2.x, but cannot resolve
696        data loss issues in a running BASE 2 server due to imperfect
697        migration. When you start the migration tool you are required
698        to pass parameter <emphasis>"disclaimer_understood"</emphasis>
699        to the <filename>migrate_from_1.2.sh</filename>
700        script. Remember to check that the migration performed well
701        before you decide to delete your 1.2 installation.
702      </para>
703      <para>
704        Migration from the latest BASE 1.2.x release to the latest is
705        supported.
706      </para>
707    </caution>
708
709    <para>
710      Verify that your BASE 2 installation is up and running before
711      attempting migration. Preferably try to log in using the root
712      user through the web interface.
713    </para>
714
715    <para>
716      Make sure your BASE 1.2 runs with the latest
717      (<emphasis>pristine</emphasis>) schema
718      version, <emphasis>i.e.,</emphasis> the migration will only
719      support an unmodified BASE 1.2 installation. If you have an out
720      of date schema version, please upgrade to the latest schema
721      using BASE 1.2 tools before migrating. If you have made local
722      changes to the BASE 1.2 schema you need to patch the BASE 2
723      schema as well as make proper changes to the migration program.
724    </para>
725
726    <para>
727      There is currently no way to restart a migration. The behaviour
728      of migration is controlled
729      through <filename>migration.properties</filename> file, but you
730      should know what you do when you change parameters in this file.
731    </para>
732
733    <para>
734      Migration is performed with the following steps:
735      <orderedlist>
736
737        <listitem>
738          <para>
739            To transfer files from BASE 1.2 (default migration
740            behaviour), you must have file system access to BASE 1.2
741            files, <emphasis>i.e.,</emphasis> the <filename
742            class="directory">/path/to/base1.2/data</filename>
743            directory containing directories
744            <filename class="direcotry">rawdata</filename>,
745            <filename class="direcotry">uploads</filename>,
746            <filename class="direcotry">protocols</filename>, ...
747          </para>
748        </listitem>
749
750        <listitem>
751          <para>
752            Change settings in the file
753            <filename>/path/to/base/dist/www/WEB-INF/classes/migrate.properties</filename>.
754            The available options are commented:
755            <itemizedlist>
756              <listitem>
757                <para>
758                  Modify <emphasis>db1.*</emphasis> parameters to
759                  match your BASE 1.2 installation.
760                </para>
761              </listitem>
762              <listitem>
763                <para>
764                  Set <emphasis>userfiles</emphasis> (note, this is
765                  not the same parameter as
766                  in <filename>base.config</filename>) to point to the
767                  directory containing the BASE 1.2 files (defined in a
768                  previous step above).
769                </para>
770              </listitem>
771              <listitem>
772                <para>
773                  Set the <emphasis>pluginDir</emphasis> to point to
774                  the directory where your BASE 1.2 plug-ins are
775                  installed. The default is
776                  <filename
777                  class="direcotry">/usr/local/base/plugins</filename>.
778                </para>
779              </listitem>
780              <listitem>
781                <para>
782                  Modify <emphasis>root.password</emphasis>.
783                </para>
784              </listitem>
785              <listitem>
786                <para>
787                  Change the <emphasis>deletefiles</emphasis> setting
788                  wisely. If you
789                  set <emphasis>deletefiles=yes</emphasis> all BASE
790                  1.2 files will be physically removed when copied to
791                  BASE 2. Leave this options
792                  as <emphasis>deletefiles=no</emphasis> unless you
793                  are absolutely sure of what you are doing.
794                </para>
795              </listitem>
796            </itemizedlist>
797          </para>
798        </listitem>
799
800        <listitem>
801          <para>
802            Run migration utility: <programlisting>
803cd /path_to_base/dist/bin
804./migrate_from_1.2.sh
805</programlisting>
806          </para>
807        </listitem>
808
809        <listitem>
810          <para>
811            Migration done! Happy BASEing.
812          </para>
813        </listitem>
814
815      </orderedlist>
816
817    </para>
818
819  </sect1>      <!-- Migration instructions -->
820
821
822
823  <sect1 id="installation_upgrade.jobagents">
824    <title>Installing job agents</title>
825    <para>TODO</para>
826  </sect1>
827
828</chapter>
Note: See TracBrowser for help on using the repository browser.