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

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

Changing the pesky "a (ä) character to a.

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