source: branches/2.8-stable/doc/src/docbook/admindoc/installation_upgrade.xml @ 4504

Last change on this file since 4504 was 4504, checked in by Nicklas Nordborg, 14 years ago

Fixes #1080: Extensions: Manual scan fails.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 52.9 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 4504 2008-09-11 06:22:51Z nicklas $
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 3
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 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 current BASE server.
46  </para>
47
48  <para>
49    The first time installation is only to be performed once,
50    optionally followed by a migration. The migration can only be done
51    to a pristine (empty) BASE version 2 server with one exception; The
52    migration can be restarted if it fails during the RawBioAssaysData
53    transfer. For all other failure points the migration has to be
54    restarted with an empty database. Migration from several BASE
55    version 1 installations to one BASE server is not supported.
56  </para>
57
58  <para>
59    The instructions here assume
60    that <ulink url="http://tomcat.apache.org/">Apache Tomcat 6</ulink> is used
61    on the server side. Other servlet engines may work but we only
62    test with Tomcat.
63  </para>
64
65
66  <sect1 id="installation_upgrade.upgrade">
67    <title>Upgrade instructions</title>
68
69    <important id="lowess_bug">
70      <title>Bug in the LOWESS plug-in affecting BASE version 2.0 -- 2.7.1</title>
71      <para>
72      BASE 2.7.2 fixes a serious bug in the LOWESS plug-in shipped
73      as a part of the BASE package. The bug is found in all
74      BASE versions between 2.0 and 2.7.1, and has caused incorrect normalization values to be
75      calculated. All data that has been normalized with the LOWESS plug-in prior
76      to BASE 2.7.2 should be considered invalid and needs to be re-normalized with
77      the fixed version. Downstream analysis steps that has used the incorrectly
78      normalized data also needs to be redone. For more information about the bug see
79      <ulink url="http://base.thep.lu.se/ticket/1077">http://base.thep.lu.se/ticket/1077</ulink>
80      </para>
81     
82      <para>
83      BASE 2.7.2 includes a utility for finding all experiments/bioassay sets that
84      includes data normalized with the LOWESS plug-in. An administrator can use
85      this utility to extract a list of all experiments/bioassay sets that needs to be fixed.
86      The utility can also tag the name of the found experiments/bioassay sets with
87      <code>FIX LOWESS</code> to make it easier to find data that needs to be fixed.
88      </para>
89     
90      <para>
91      The utility can't see any difference between data normalized with the
92      old version and the fixed version. It will simply report all data that
93      has been normalized with the LOWESS plug-in. Only use the utility a single
94      time right after the upgrade to BASE 2.7.2.
95      </para>
96     
97      <para>
98      The utility is a command line program that should be executed on the BASE
99      application (web) server.
100      </para>
101     
102      <programlisting>
103<![CDATA[
104cd <base-dir>/bin
105./onetimefix.sh lowess_warn -u <login> -p <password> -f
106]]>
107</programlisting>
108     
109      <para>
110        We recommend running the utility as the root user. The <option>-f</option>
111        option is optional. If it is included the found experiments/bioassay sets
112        are tagged with <code>FIX LOWESS</code>, otherwise only a list with the
113        information is generated.
114      </para>
115     
116    </important>
117
118    <important id="tomcat6">
119      <title>BASE 2.7 requires Tomcat 6 or higher</title>
120      <para>
121        If you are upgrading from older BASE versions to BASE 2.7 or higher
122        you must also make sure that you are running Tomcat 6 or higher.
123        Earlier BASE versions only required Tomcat 5.5. If you are not
124        already running Tomcat 6 you need to upgrade. Other servlet
125        engines may work if they implement the Servlet 2.5 and JSP
126        2.1 specifications.
127      </para>
128    </important>
129
130    <important id="dropindexes">
131      <title>Upgrading from BASE 2.4.3 or lower to 2.4.4 or higher</title>
132      <para>
133        Older releases of BASE 2 used to create indexes for many columns
134        in the dynamic database. The same columns are part of the primary
135        key for the tables so the indexes are not really needed. The
136        result is very bad performance since the database engine sometimes
137        get stuck in "index update" mode making the entire server
138        very slow. BASE 2.4.4 no longer creates the indexes. Indexes on
139        existing tables should be dropped to increase the performance.
140        Tests have shown a 50-90% decrease in execution time for some
141        plug-ins
142        (<ulink url="http://base.thep.lu.se/ticket/294">http://base.thep.lu.se/ticket/294</ulink>).
143      </para>
144      <para>
145        Removing the indexes is very simple. <emphasis>After the server
146        has been upgraded</emphasis> following the usual instructions below, issue the
147        the following commands:
148      </para>
149   
150      <programlisting>
151cd &lt;basedir&gt;/bin
152./dynamicdb.sh -v -dropindexes
153</programlisting>
154
155      <para>
156        Skip the <option>-dropindexes</option> option to do a dry
157        run without actually deleting the indexes.
158      </para>
159    </important>
160
161    <para>
162      As always, backup your database before attempting an
163      upgrade. The BASE team performs extensive testing before
164      releasing a new version of BASE but there are always a
165      possibility for unexpected events during upgrades. In upgrades
166      requiring a change in the underlying database there is no
167      (supported) way to revert to a previous version of BASE using
168      BASE tools, you need to use your backup for this use case.
169    </para>
170
171    <para>
172      The strategy here is to install the new BASE release to another
173      directory than the one in use. This requires transfer of
174      configuration settings to the new install but more on that
175      below.
176    </para>
177
178    <variablelist>
179      <varlistentry>
180        <term>Shut down the Tomcat server</term>
181        <listitem>
182          <para>
183            If the BASE application is not shut down already, it is
184            time to do it now. Do something like <command>sudo
185            /etc/init.d/tomcat6.0 stop</command>
186          </para>
187        </listitem>
188      </varlistentry>
189
190      <varlistentry>
191        <term>Rename your current server</term>
192        <listitem>
193          <para>
194            Rename your current BASE installation <command>mv
195              /path/to/base /path/to/base_old</command>.
196          </para>
197        </listitem>
198      </varlistentry>
199
200      <varlistentry>
201        <term>Download and unpack BASE</term>
202        <listitem>
203          <para>
204            There are several ways to download BASE. Please refer to
205            section <xref linkend="resources.home_page.download"/> for
206            information on downloading BASE, and select the item
207            matching your download option:
208          </para>
209
210          <variablelist>
211            <varlistentry>
212              <term><emphasis>Pre-compiled package</emphasis></term>
213              <listitem>
214                <para>
215                  If you selected to download a pre-compiled package,
216                  unpack the downloaded file with <command>tar zxpf
217                  base-...tar.gz</command>.
218                </para>
219              </listitem>
220            </varlistentry>
221
222            <varlistentry>
223              <term><emphasis>Source package</emphasis></term>
224              <listitem>
225                <para>
226                  If you selected to download a source package, unpack
227                  the downloaded file with <command>tar zxpf
228                  base-...src.tar.gz</command>. Change to the new
229                  directory, and issue <command>ant
230                  package.bin</command>. This will create a binary
231                  package in the current directory. Unpack this new
232                  package (outside of the source file hierarchy).
233                </para>
234              </listitem>
235            </varlistentry>
236
237            <varlistentry>
238              <term><emphasis>Subversion checkout</emphasis></term>
239              <listitem>
240                <para>
241                  This option is for advanced users only and is not
242                  covered here. Please refer to
243                  <xref linkend="core_ref.build"/> for information on
244                  this download option.
245                </para>
246              </listitem>
247            </varlistentry>
248
249          </variablelist>
250        </listitem>
251
252      </varlistentry>
253
254      <varlistentry>
255        <term>Transfer files and settings</term>
256        <listitem>
257          <para>
258            Settings from the previous installation must be
259            transferred to the new installation. This is most easily
260            done by comparing the configuration files from the
261            previous install with the new files. Do not just copy the
262            old files to the new install since new options may have
263            appeared.
264          </para>
265          <para>
266            In the main BASE configuration file,
267            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>,
268            fields that needs to be transferred are usually
269            <emphasis>db.username</emphasis>,
270            <emphasis>db.password</emphasis>,
271            and <emphasis>userfiles</emphasis>.
272          </para>
273          <para>
274            Local settings in the raw data
275            tables, <filename>&lt;base-dir&gt;/www/WEB-INF/classes/raw-data-types.xml</filename>,
276            may need to be transferred. This also includes all files in
277            the <filename>&lt;base-dir&gt;/www/WEB-INF/classes/raw-data-types</filename> and
278            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/extended-properties</filename>
279            directories.
280          </para>
281        </listitem>
282      </varlistentry>
283
284      <varlistentry>
285        <term>Updating database schema</term>
286        <listitem>
287          <para>
288            It is recommended that you also perform an update of your
289            database schema.  Running the update scripts are not
290            always necessary when upgrading BASE, but the running the
291            update scripts are safe even in cases when there is no
292            need to run them. Change directory
293            to <filename
294            class="directory">&lt;base-dir&gt;/bin/</filename> and issue
295<programlisting>
296sh ./updatedb.sh [base_root_login] <emphasis>base_root_password</emphasis>
297sh ./updateindexes.sh
298</programlisting>
299            where <emphasis>base_root_login</emphasis> is the login
300            for the root user and <emphasis>base_root_password</emphasis> is the
301            password. The login is optional. If not specified,
302            <constant>root</constant> is used as the login.
303          </para>
304        </listitem>
305      </varlistentry>
306
307      <varlistentry>
308        <term>Remove Tomcat cache</term>
309        <listitem>
310          <para>
311            As Tomcat user, remove cached files and directories. Do
312            something like
313<programlisting>cd /usr/share/apache-tomcat-6.0/
314rm -rf work/Catalina</programlisting>
315          </para>
316        </listitem>
317      </varlistentry>
318
319      <varlistentry>
320        <term>Start Tomcat</term>
321        <listitem>
322          <para>
323            Start the Tomcat server: <command>sudo
324              /etc/init.d/tomcat6.0 start</command>
325          </para>
326        </listitem>
327      </varlistentry>
328
329    </variablelist>
330
331    <para>
332      Done! Upgrade of BASE is finished.
333    </para>
334
335  </sect1>      <!-- Upgrade instructions -->
336
337
338  <sect1 id="installation_upgrade.jobagents">
339    <title>Installing job agents</title>
340
341    <para>
342      It is important to understand that the BASE application can be
343      spread on to several computers. The main BASE application is
344      serving HTTP requests, the underlying database engine is
345      providing storage and persistence of data, and job agents can be
346      installed on computers that will serve the BASE installation
347      with computing power and perform analysis and run plug-in. In a
348      straight forward setup one computer provides all services needed
349      for running BASE. From this starting point it is easy to add
350      computers to shares load from the BASE server by installing job
351      agents on these additional computers.
352    </para>
353
354    <para>
355      A job agent is a program running on a computer regularly
356      checking the BASE job queue for jobs awaiting execution. When
357      the job agent finds a job that it is enabled to execute, it
358      loads the plug-in and executes it. Job agents will in this way
359      free up resources on the BASE application server, and thus allow
360      the BASE server to concentrate on serving web pages. Job agents
361      are optional and must be installed and setup
362      separately. However, BASE is prepared for job agent setup and to
363      utilize the agents, but the agent are not required.
364    </para>
365
366    <para>
367      A job agent supports many configuration options that are not
368      supported by the internal job queue. For example, you can
369      <itemizedlist>
370        <listitem>
371          <para>
372            Specify exactly which plug-ins each job agent should be
373            able to execute.
374          </para>
375        </listitem>
376        <listitem>
377          <para>
378            Give some plug-ins higher priority than other plug-ins.
379          </para>
380        </listitem>
381        <listitem>
382          <para>
383            Specify which users/groups/projects should be able to use
384            a specific job agent.
385          </para>
386        </listitem>
387        <listitem>
388          <para>
389            Override memory settings and more for each plug-in.
390          </para>
391        </listitem>
392        <listitem>
393          <para>
394            Execute plug-ins in separate processes. Thus, a misbehaving
395            plug-in cannot bring the main application server down.
396          </para>
397        </listitem>
398        <listitem>
399          <para>
400            Add more computers with job agents as needed.
401          </para>
402        </listitem>
403      </itemizedlist>
404      All these options make it possible to create a very flexible
405      setup. For example one job agent can be assigned for importing
406      data only, another job agent can be assigned for running
407      analysis plug-ins for specific project only, and a third may be a
408      catch-all job agent that performs all low-priority jobs.
409    </para>
410
411    <sect2 id="installation_upgrade.jobagents.serverside">
412      <title>BASE application server side setup</title>
413      <para>
414        <variablelist>
415          <varlistentry>
416            <term>Make sure the internal job queue doesn't execute all plug-ins</term>
417            <listitem>
418              <para>
419                The setting <command>jobqueue.internal.runallplugins</command>
420                should be set to <command>false</command> for the
421                BASE server. This setting is found in
422                the <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
423                file. The changes will not take effect until the
424                application server is restarted.
425              </para>
426             
427              <note>
428                Prior to BASE 2.5 the internal job queue had to be disabled
429                completely. This is no longer the case since it is possible to
430                enable/disable the internal job queue separately for
431                each plug-in.
432              </note>
433             
434            </listitem>
435          </varlistentry>
436          <varlistentry id="installation_upgrade.jobagent.user_account">
437            <term>Enable the job agent user account</term>
438            <listitem>
439              <para>
440                During installation of BASE a user account is created
441                for the job agent. This account is used by the job
442                agents to log on to BASE. The account is disabled by
443                default and must be enabled. Enable the account and
444                set a password using the BASE web interface.
445                The same password must also be set in the
446                <filename>jobagent.properties</filename> file, see
447                item
448                <xref linkend="installation_upgrade.jobagent.client.properties"/>
449                below.
450              </para>
451            </listitem>
452          </varlistentry>
453        </variablelist>
454      </para>
455    </sect2>
456
457    <sect2 id="installation_upgrade.jobagents.database">
458      <title>Database server setup</title>
459      <para>
460        <variablelist>
461          <varlistentry id="installation_upgrade.jobagent.database">
462            <term>Create a user account on the database</term>
463            <listitem>
464              <para>
465                This is the similar to granting database access for
466                the BASE server user in the in the regular BASE
467                installation, cf.
468                <xref
469                linkend="installation_upgrade.installation.database"/>.
470                You must create an account in the database that is
471                allowed to connect from the job agent server. MySQL
472                example:
473<programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password';
474GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting>
475
476                Replace <command>job.agent.host</command> with the
477                host name of the server that is going to run the job
478                agent. You should also set password. This password is
479                used in item
480                <xref linkend="installation_upgrade.jobagent.client.config"/>
481                below in job agent server setup. You can use the same
482                database user and password as in the regular database
483                setup.
484              </para>
485            </listitem>
486          </varlistentry>
487        </variablelist>
488      </para>
489    </sect2>
490
491    <sect2 id="installation_upgrade.jobagents.client">
492      <title>Job agent client setup</title>
493      <para>
494        <variablelist>
495          <varlistentry>
496            <term>Download and unpack a regular BASE distribution</term>
497            <listitem>
498              <para>
499                You <emphasis>must</emphasis> use the same version on
500                the web server and all job agents. You find the
501                downloads at
502                <ulink
503                url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink>
504              </para>
505            </listitem>
506          </varlistentry>
507          <varlistentry id="installation_upgrade.jobagent.client.config">
508            <term>Edit the <filename>base.config</filename> file</term>
509            <listitem>
510              <para>
511                The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
512                file must be configured as in regular BASE
513                installation, cf.
514                <xref
515                linkend="installation_upgrade.installation.configuration"/>,
516                to use the same database as the web server
517                application. The most important settings are
518                <itemizedlist>
519                  <listitem>
520                    <para>
521                      <command>db.username</command>: The database
522                      user you created in item
523                      <xref
524                      linkend="installation_upgrade.jobagent.database"/>
525                      above.
526                    </para>
527                  </listitem>
528                  <listitem>
529                    <para>
530                      <command>db.password</command>: The password for
531                      the user.
532                    </para>
533                  </listitem>
534                  <listitem>
535                    <para>
536                      <command>db.url</command>: The connection url to
537                      the database.
538                    </para>
539                  </listitem>
540                  <listitem>
541                    <para>
542                      <command>userfiles</command>: The path to the
543                      directory where user files are located. This
544                      directory must be accessible from all job
545                      agents, i.e., by nfs or other file system
546                      sharing method.
547                    </para>
548                  </listitem>
549                </itemizedlist>
550                See the <xref linkend="appendix.base.config"/> for
551                more information about the settings in
552                the <filename>base.config</filename> file.
553              </para>
554            </listitem>
555          </varlistentry>
556          <varlistentry id="installation_upgrade.jobagent.client.properties">
557            <term>Edit
558            the <filename>jobagent.properties</filename> file</term>
559            <listitem>
560              <para>
561                The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/jobagent.properties</filename>
562                file contains settings for the job agent. The most
563                important ones to specify value for are
564                <itemizedlist>
565                  <listitem>
566                    <para>
567                      <command>agent.password</command>: The password
568                      you set for the job agent user account in item
569                      <xref
570                      linkend="installation_upgrade.jobagent.user_account"/>
571                      above.
572                    </para>
573                  </listitem>
574                  <listitem>
575                    <para>
576                      <command>agent.id</command>: An ID that must be
577                      unique for each job agent accessing the BASE application.
578                    </para>
579                  </listitem>
580                  <listitem>
581                    <para>
582                      <command>agent.remotecontrol</command>: The
583                      name/ip address of the web server if you want it
584                      to be able to display info about running
585                      jobs. The job agent will only allow connections
586                      from computers specified in this setting.
587                    </para>
588                  </listitem>
589                </itemizedlist>
590              </para>
591              <para>
592                The <filename>jobagent.properties</filename> file
593                contains many more configuration options. See
594                the <xref linkend="appendix.jobagent.properties"/> for
595                more information.
596              </para>
597            </listitem>
598          </varlistentry>
599          <varlistentry>
600            <term>Register the job agent</term>
601            <listitem>
602              <para>
603                From the <filename>bin</filename> directory, register
604                the job agent with
605                <programlisting>./jobagent.sh register</programlisting>
606              </para>
607            </listitem>
608          </varlistentry>
609          <varlistentry>
610            <term>Start the job agent</term>
611            <listitem>
612              <para>
613                From the <filename>bin</filename> directory, start the
614                job agent with
615                <programlisting>./jobagent.sh start &amp;</programlisting>
616              </para>
617              <para>
618                See the <xref linkend="appendix.jobagent.sh"/>
619                for more information about what you can do
620                with the job agent command line interface.
621              </para>
622            </listitem>
623          </varlistentry>
624        </variablelist>
625      </para>
626    </sect2>
627
628    <sect2 id="installation_upgrade.jobagents.configuration">
629      <title>Configuring the job agent</title>
630      <para>
631        Before the job agent starts executing jobs for you it must be
632        configured. The configuration is done through the BASE web
633        interface. See <xref linkend="plugins.jobagents" />
634        <variablelist>
635          <varlistentry>
636            <term>Configure the plug-ins the job agent should handle</term>
637            <listitem>
638              <para>
639                <itemizedlist>
640                  <listitem>
641                    <para>
642                      Go to the
643                      <menuchoice>
644                        <guimenu>Administrate</guimenu>
645                        <guisubmenu>Plugins</guisubmenu>
646                        <guimenuitem>Job agents</guimenuitem>
647                      </menuchoice> menu.
648                    </para>
649                  </listitem>
650                  <listitem>
651                    <para>
652                      Select the job agent and click on the &gbEdit;
653                      button.
654                    </para>
655                  </listitem>
656                  <listitem>
657                    <para>
658                      On the <guilabel>Plugins</guilabel> tab you can
659                      specify which plug-ins the job agent should
660                      handle. Note that if you have installed external
661                      plug-ins on the web server, those plug-ins must be
662                      installed on the job agent as well. It is
663                      possible to specify different paths to the JAR
664                      file for each job agent.
665                    </para>
666                  </listitem>
667                </itemizedlist>
668              </para>
669            </listitem>
670          </varlistentry>
671          <varlistentry>
672            <term>Grant users access to the job agent</term>
673            <listitem>
674              <para>
675                Use the regular <guilabel>Share</guilabel>
676                functionality to specify which users/groups/projects
677                should be able to use the job agent. You must give
678                them at least <command>USE</command> permission.
679              </para>
680            </listitem>
681          </varlistentry>
682        </variablelist>
683      </para>
684    </sect2>
685
686  </sect1>      <!-- job agent setup -->
687
688
689  <sect1 id="installation_upgrade.installation">
690    <title>Installation instructions</title>
691
692    <variablelist>
693
694      <varlistentry>
695        <term>Java</term>
696        <listitem>
697          <para>
698            Download and install Java SDK 1.6 (aka Java 6), available from
699            <ulink url="http://java.sun.com/" />.
700          </para>
701        </listitem>
702      </varlistentry>
703
704      <varlistentry>
705        <term>Tomcat</term>
706        <listitem>
707          <para>
708            Download and install Apache Tomcat 6.0.14 or later, available
709            from <ulink
710            url="http://tomcat.apache.org" />.
711
712            It is a good idea to specify the maximum allowed memory
713            that Tomcat can use. The default setting is usually not
714            large enough. If you are using Tomcat 6.0.18 or higher
715            you also need to disable strict parsing of JSP files.
716           
717            To do this you have to set Java startup options
718            in the <code>CATALINA_OPTS</code> environment variable.
719           
720            Basically add the next line (as a single line) close to the top of
721            the <filename>catalina.sh</filename> script that comes
722            with Tomcat
723            (directory <filename
724            class="directory">bin</filename>):
725<programlisting>CATALINA_OPTS="-Xmx500m
726-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false"</programlisting>
727          </para>
728          <para>
729            For more information about Tomcat options see
730            <ulink url="http://tomcat.apache.org/tomcat-6.0-doc/index.html" />.
731          </para>
732        </listitem>
733      </varlistentry>
734
735      <varlistentry>
736        <term>Set up SQL database</term>
737        <listitem>
738          <para>
739            BASE
740            utilize <ulink
741            url="http://www.hibernate.org/">Hibernate</ulink> for
742            object persistence to a relational database. Hibernate
743            supports many database engines, but so far we only work
744            with <ulink url="http://www.mysql.com">MySQL</ulink>
745            and <ulink
746            url="http://www.postgresql.org/">PostgreSQL</ulink>.
747          </para>
748
749          <variablelist>
750            <varlistentry>
751              <term>MySQL</term>
752              <listitem>
753                <para>
754                  Download and install MySQL (tested with version
755                  5.0), available from
756                  <ulink url="http://www.mysql.com/" />. You need to
757                  be able to connect to the server over TCP, so
758                  the <emphasis>skip-networking</emphasis> option
759                  must <command>not</command> be used. The InnoDB
760                  table engine is also needed, so do not disable them
761                  (not that you would) but you may want to tune the
762                  InnoDB behaviour before creating BASE
763                  databases. BASE comes pre-configured for MySQL so
764                  there is no need to change database settings in the
765                  BASE configuration files.
766                </para>
767              </listitem>
768            </varlistentry>
769            <varlistentry>
770              <term>PostgreSQL</term>
771              <listitem>
772                <para>
773                  PostgreSQL 8.2 seems to be working very well with
774                  BASE and Hibernate. Download and install PostgreSQL,
775                  available from
776                  <ulink url="http://www.postgresql.org/" />. you must
777                  edit
778                  your <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
779                  file. Uncomment the settings for PostgreSQL and
780                  comment out the settings for MySQL.
781                </para>
782               
783                <note>
784                  <para>
785                  PostgreSQL versions prior to 8.2 have a non-optimal solution
786                  for locking rows in certain situations. This may cause two
787                  seemingly independent transactions to lock if they just
788                  reference a common database row. This may happen, for example,
789                  when importing raw data that have references to the same
790                  reporters. The problem has been solved in PostgreSQL 8.2.
791                  </para>
792                </note>
793               
794              </listitem>
795            </varlistentry>
796          </variablelist>
797
798        </listitem>
799      </varlistentry>
800
801      <varlistentry>
802        <term>BASE (download and unpacking)</term>
803        <listitem>
804          <para>
805            <ulink
806            url="http://base.thep.lu.se/wiki/DownloadPage">Download
807            BASE</ulink> and unpack the downloaded file,
808            i.e. <command>tar zxpf base-...tar.gz</command>. If you
809            prefer to have the bleeding edge version of BASE, perform
810            a checkout of the source from the subversion repository
811            (subversion checkout instructions at
812            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
813            trac site</ulink>).
814          </para>
815          <para>
816            If you choose to download the binary package, skip to the
817            next item. The rest of us, read on and compile BASE. If
818            you downloaded a source distribution, unpack the
819            downloaded file <command>tar zxpf
820            base-...src.tar.gz</command>, or you may have performed a
821            subversion checkout.  Change to the 'root' base2
822            directory, and issue <command>ant
823            package.bin</command>. This will create a binary package
824            in the base2 'root' directory. Unpack this new package
825            (outside of the source file hierarchy), and from now on
826            the instructions are the same irrespective where you got
827            the binary package.
828          </para>
829          <para>
830            <emphasis>This section is intended for advanced users and
831              programmers only. In cases when you want to change the
832              BASE code and try out personalized features it may be
833              advantageous to run the tweaked BASE server against the
834              development tree. Instructions on how to accomplish this
835              is available in the
836              <ulink
837              url="http://base.thep.lu.se/chrome/site/doc/development/build.html">building
838              BASE document</ulink>. When you return back after
839              compiling in the subversion tree you can follow the
840              instruction here (with obvious changes to
841              paths).</emphasis>
842          </para>
843        </listitem>
844      </varlistentry>
845
846      <varlistentry id="installation_upgrade.installation.database">
847        <term>BASE (database engine)</term>
848        <listitem>
849          <para>
850            Instructions for MySQL and PostgreSQL are available
851            below. The database names (base2 and base2dynamic is used
852            here), the <emphasis>db_user</emphasis>, and
853            the <emphasis>db_password</emphasis> can be changed during
854            the creation of the databases. It is recommended to change
855            the <emphasis>db_password</emphasis>, the other changes
856            can be made if desired. The database names,
857            the <emphasis>db_user</emphasis>, and
858            the <emphasis>db_password</emphasis> are needed in a later
859            step below when configuring BASE.
860          </para>
861          <note>
862            Note that the <emphasis>db_user</emphasis> name
863            and <emphasis>db_password</emphasis> set here is used
864            internally by BASE in communication with the database and
865            is never used to log on to the BASE application.
866          </note>
867          <variablelist>
868            <varlistentry>
869              <term>MySQL</term>
870              <listitem>
871                <para>
872                  Create a new database for BASE, and add a
873                  <emphasis>db_user</emphasis> with at least
874                  <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
875                  <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
876                  <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
877                  <emphasis>INDEX</emphasis>,
878                  and <emphasis>ALTER</emphasis> permission for the
879                  new database. To do this, connect to your MySQL
880                  server and issue the next lines:
881<programlisting>CREATE DATABASE base2;
882CREATE DATABASE base2dynamic;
883GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
884GRANT ALL ON base2dynamic.* TO db_user@localhost;</programlisting>
885                </para>
886                <para>
887                  The <filename>&lt;base-dir&gt;/misc/sql/createdb.mysql.sql</filename>
888                  file contains the above statements and can be used
889                  by the <filename>mysql</filename> command-line tool
890                  (remember to edit
891                  the <emphasis>db_user</emphasis>,
892                  <emphasis>db_password</emphasis>,
893                  and the database names in the script file before
894                  executing the command): <command>mysql -uroot -p
895                  &lt; ./misc/sql/createdb.mysql.sql</command>. The
896                  header in the script file contains further
897                  information about the script.
898                </para>
899              </listitem>
900            </varlistentry>
901            <varlistentry>
902              <term>PostgreSQL</term>
903              <listitem>
904                <para>
905                  Create a new database for BASE, and add a
906                  <emphasis>db_user</emphasis> with the proper
907                  privileges. To do this, log in as your PostgreSQL
908                  user and issue these lines (omit comments):
909<programlisting>createuser db_user -P
910  # this will prompt for an password for the new user, and issue two
911  # more question that should be answered with character 'n' for no.
912createdb --owner db_user --encoding UNICODE base2
913psql base2
914  # this will start the psql command line tool. Issue the next line
915  # within the tool and quit with a '\q'.
916CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting>
917                  The <filename>&lt;base-dir&gt;/misc/sql/createdb.postgresql.sql</filename>
918                  file contains the above statements and can be used
919                  by the <filename>psql</filename> command-line tool:
920                  <command>psql -f ./misc/sql/createdb.posgres.sql
921                    template1</command> The header in the script file
922                  contains further information about the script.
923                </para>
924              </listitem>
925            </varlistentry>
926          </variablelist>
927        </listitem>
928      </varlistentry>
929
930      <varlistentry>
931        <term>BASE (file storage setup)</term>
932        <listitem>
933          <para>
934            An area for file storage must be setup. Create an empty
935            directory in a proper location in your file system, and
936            set the owner to be the same as the one that the Tomcat
937            server will be running as. Remember this location for
938            later use.
939          </para>
940        </listitem>
941      </varlistentry>
942
943      <varlistentry id="installation_upgrade.installation.configuration">
944        <term>BASE (configuration)</term>
945        <listitem>
946          <para>
947            Basic BASE configuration is done in
948            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>:
949            <itemizedlist>
950              <listitem>
951                Uncomment the database engine section that match your setup.
952              </listitem>
953              <listitem>
954                Modify the <emphasis>db.url</emphasis>,
955                <emphasis>db.dynamic.catalog</emphasis>,
956                <emphasis>db.username</emphasis>,
957                and <emphasis>db.password</emphasis> settings to match
958                your choice above. (<emphasis>database host and
959                database name (e.g. base2)</emphasis>,
960                <emphasis>e.g. base2dynamic</emphasis>,
961                <emphasis>db_user</emphasis>, and
962                <emphasis>db_password</emphasis>, respectively.)
963              </listitem>
964              <listitem>
965                Modify the <emphasis>userfiles</emphasis> setting to
966                match your choice above.
967              </listitem>
968            </itemizedlist>
969            See the <xref linkend="appendix.base.config"/> for more
970            information about the settings in
971            the <filename>base.config</filename> file.
972          </para>
973          <para>
974            <emphasis>Optional but recommended.</emphasis> You may want
975            to modify extended properties to fit your needs. Extended
976            properties are defined in
977            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/extended-properties.xml</filename>.
978            There is an
979            administrator <ulink
980            url="http://base.thep.lu.se/chrome/site/doc/admin/extended-properties.html">document
981            discussing extended properties</ulink> available. If you
982            plan to perform a migration of a BASE version 1.2 database you
983            should probably not remove any extended properties
984            columns (this is not tested so the outcome is currently
985            undefined). However, adding columns does not affect
986            migration.
987          </para>
988        </listitem>
989      </varlistentry>
990
991      <varlistentry>
992        <term>BASE (database initialization)</term>
993        <listitem>
994          <para>
995            Change directory to
996            <filename class="directory">&lt;base-dir&gt;/bin</filename>
997            and run <filename>initdb.sh</filename> as
998<programlisting>./initdb.sh [base_root_login] base_root_password</programlisting>
999
1000            <important>
1001            <para>
1002            The <emphasis>base_root_login</emphasis> and
1003            <emphasis>base_root_password</emphasis> you use here
1004            is given to the BASE web application root user account.
1005            The <emphasis>base_root_login</emphasis> is optional. If
1006            not specified, <constant>root</constant> is used for
1007            the login.
1008            </para>
1009            </important>
1010            If the initialisation script fail, it is most probably a
1011            problem related to the underlying database. Make sure that
1012            the database accepts network connection and make sure that
1013            <emphasis>db_user</emphasis> has proper credentials.
1014          </para>
1015        </listitem>
1016      </varlistentry>
1017
1018      <varlistentry>
1019        <term>BASE and Tomcat</term>
1020        <listitem>
1021          <para>
1022            Either move the <filename
1023            class="directory">&lt;base-dir&gt;/www</filename> directory
1024            to the Tomcat <filename class="directory">webapps</filename>
1025            directory or create a symbolic link from the Tomcat
1026            <filename class="directory">webapps</filename> directory to
1027            the <filename class="directory">&lt;base-dir&gt;/www</filename>
1028            directory
1029<programlisting>cd /path/to/tomcat/webapps
1030ln -s /path_to_base/www base2</programlisting>
1031          </para>
1032          <para>
1033            If you plan to install extensions you should make sure that
1034            the <filename class="directory">&lt;base-dir&gt;/www/extensions</filename>
1035            directory is writable by the user account Tomcat is running as.
1036          </para>
1037          <para>
1038            Start/restart Tomcat, and try http://hostname:8080/base2
1039            (change <emphasis>hostname</emphasis> to your hostname) in
1040            your favourite browser. The BASE log-in page should appear
1041            after a few seconds.
1042          </para>
1043        </listitem>
1044      </varlistentry>
1045
1046      <varlistentry>
1047        <term>BASE, Apache, and Apache/Tomcat connector</term>
1048        <listitem>
1049          <para>
1050            <emphasis>This step is optional</emphasis>.
1051          </para>
1052          <para>
1053            If you want run the Tomcat server through the Apache web
1054            server, you need to install the Apache version 2 web
1055            server, available
1056            from <ulink
1057            url="http://www.apache.org/">http://www.apache.org/</ulink>,
1058            and a apache-tomcat connector, available
1059            from <ulink
1060            url="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</ulink>.
1061            So, we got you there;-) To be honest, this step is not
1062            really well documented since we previously used SuSE 9.3
1063            on our demo/test server, and apache/tomcat/mod_jk comes
1064            pre-installed. The current server does not use the
1065            apache/tomcat connector. What you need to do is something
1066            like this
1067            <itemizedlist>
1068              <listitem>
1069                Get that Tomcat server running in stand-alone
1070                mode.
1071              </listitem>
1072              <listitem>
1073                Get the Apache 2 server running.
1074              </listitem>
1075              <listitem>
1076                Install mod_jk. Note, different version are used for
1077                apache 1.3 and 2. In SuSE 9.3 this step is done by
1078                installing <filename>mod_jk-ap20</filename>.
1079              </listitem>
1080              <listitem>
1081                Create a <filename>workers.properties</filename> file
1082                in the
1083                Tomcat <filename class="directory">base</filename>
1084                directory (commonly copied from a template).
1085              </listitem>
1086              <listitem>
1087                Create a <filename>jk.conf</filename> file in the
1088                apache <filename class="directory">conf</filename>
1089                directory (commonly copied from a template), and make
1090                sure that <emphasis>jk</emphasis> is added to the
1091                modules to be loaded when apache starts.
1092              </listitem>
1093              <listitem>
1094                In <filename>jk.conf</filename> add the lines below
1095                and change paths appropriately.
1096<programlisting># The following lines makes apache aware of the location of
1097# the /base2 context
1098Alias /base2 "/srv/www/tomcat6/base/webapps/base2"
1099&lt;Directory "/srv/www/tomcat6/base/webapps/base2"&gt;
1100Options Indexes FollowSymLinks
1101allow from all
1102&lt;/Directory&gt;
1103# The following lines mounts all base2 jsp files to Tomcat
1104JkMount /base2 ajp13
1105JkMount /base2/* ajp13
1106# The following lines prohibits users from directly accessing WEB-INF
1107&lt;Location "/base2/WEB-INF/"&gt;
1108AllowOverride None
1109deny from all
1110&lt;/Location&gt;</programlisting>
1111              </listitem>
1112            </itemizedlist>
1113            You must restart the Apache and the Tomcat server after above steps.
1114          </para>
1115        </listitem>
1116      </varlistentry>
1117
1118      <varlistentry>
1119        <term>Setup done!</term>
1120        <listitem>
1121          <para>
1122            Happy BASEing. Now you can log on to your BASE server as
1123            user <emphasis>root</emphasis> (use
1124            the <emphasis>base_root_password</emphasis> from the
1125            database initialization step above). You should begin with
1126            creating a couple user accounts, for more information on
1127            how to create user accounts please refer to
1128            <xref linkend="user_administration"/>.
1129          </para>
1130          <para>
1131            If you are planning to perform a migration of data from
1132            BASE version 1.2.x please perform the steps in
1133            <xref linkend="installation_upgrade.migration"/> before
1134            doing anything else with your new BASE installation.
1135          </para>
1136        </listitem>
1137      </varlistentry>
1138
1139    </variablelist>
1140
1141  </sect1>      <!-- Installation instructions -->
1142
1143  <sect1 id="installation_upgrade.serverconfigurations">
1144    <title>Server configurations</title>
1145    <para>
1146      Some server configurations can be done when the installation process is finished and
1147      BASE is up and running. Log into BASE with administration rights and then
1148      open the configuration dialog from menu
1149      <menuchoice>
1150        <guimenu>Administrate</guimenu>
1151        <guimenuitem>Server settings</guimenuitem>
1152      </menuchoice>.
1153      Each tab in the configuration dialog-window is described below.
1154    </para>
1155    <variablelist>
1156      <varlistentry>
1157        <term>
1158          <guilabel>File transfer</guilabel>
1159        </term>
1160        <listitem>
1161          <helptext external_id="serverconfig.filetransfer" title="File transfer rate">
1162            <variablelist>
1163              <varlistentry>
1164                <term><guilabel>Max transfer rate</guilabel></term>
1165                <listitem>
1166                  <para>
1167                    This is a limit of how many bytes of data that should be
1168                    transferred per second when uploading files to BASE. Prefixes
1169                    like k, M or G can be used for larger values, just like
1170                    described in the tab. The limit is per ongoing upload
1171                    and the default value is 100MB/s.
1172                  </para>
1173                </listitem>
1174              </varlistentry>
1175              <varlistentry>
1176                <term><guilabel>Unlimited</guilabel></term>
1177                <listitem>
1178                  <para>
1179                    Check this to not limit the transfer rate. In this case, the
1180                    Internet connection of the server is the limit.
1181                  </para>
1182                </listitem>
1183              </varlistentry>
1184            </variablelist>
1185          </helptext>
1186        </listitem>
1187      </varlistentry>
1188      <varlistentry>
1189        <term>
1190          <guilabel>About</guilabel>
1191        </term>
1192        <listitem>
1193          <helptext external_id="serverconfig.about"
1194            title="Information about the server">
1195            <variablelist>
1196              <varlistentry>
1197                <term><guilabel>Administrator name</guilabel></term>
1198                <listitem>
1199                  <para>
1200                    Name of the responsible administrator. The name is displayed
1201                    at the bottom of each page in BASE and in the about-dialog.
1202                  </para>
1203                </listitem>
1204              </varlistentry>
1205              <varlistentry>
1206                <term><guilabel>Administrator email</guilabel></term>
1207                <listitem>
1208                  <para>
1209                    An email which the administrator can be contacted on. The
1210                    administrator name, visible at the bottom of each page, will
1211                    be linked to this email address.
1212                  </para>
1213                </listitem>
1214              </varlistentry>
1215              <varlistentry>
1216                <term><guilabel>About</guilabel></term>
1217                <listitem>
1218                  <para>
1219                    Text written in this field is displayed in the
1220                    <guilabel>About this server</guilabel> section on the login
1221                    page and in the about-dialog window. We recommend changing the
1222                    default Latin text to something meaningful, or remove it
1223                    to hide the section completely.
1224                  </para>
1225                </listitem>
1226              </varlistentry>
1227            </variablelist>
1228          </helptext>
1229        </listitem>
1230      </varlistentry>
1231      <varlistentry>
1232        <term>
1233          <guilabel>Get account</guilabel>
1234        </term>
1235        <listitem>
1236          <helptext external_id="serverconfig.getaccount"
1237            title="Instructions to get an account">
1238            <para>
1239              A description what a none-registered user should do to get
1240              an account on the particular BASE-server. This text is linked
1241              to the <guilabel>Get an account!</guilabel> link on the login
1242              page. We recommend that the Latin text is replaced with some useful
1243              information, or that it is removed to hide the link.
1244            </para>
1245          </helptext>
1246        </listitem>
1247      </varlistentry>
1248      <varlistentry>
1249        <term>
1250          <guilabel>Forgotten password</guilabel>
1251        </term>
1252        <listitem>
1253          <helptext external_id="serverconfig.password"
1254            title="Instructions when password is forgotten.">
1255            <para>
1256              A description what an user should do if the password is forgotten.
1257              This text is linked
1258              to the <guilabel>Forgot your password?</guilabel> link on the login
1259              page. We recommend that the Latin text is replaced with some useful
1260              information, or that it is removed to hide the link.
1261            </para>
1262          </helptext>
1263        </listitem>
1264      </varlistentry>
1265      <varlistentry>
1266        <term>
1267          <guilabel>Links</guilabel>
1268        </term>
1269        <listitem>
1270          <helptext external_id="serverconfig.links" title="Configurable links">
1271            <para>
1272              External configurable link-types inside BASE.
1273              <note>
1274                <para>
1275                  Only link-types that have been set will be visible in the web
1276                  client.
1277                </para>
1278              </note>
1279            </para>
1280            <variablelist>
1281              <varlistentry>
1282                <term><guilabel>Help</guilabel></term>
1283                <listitem>
1284                  <para>
1285                    Links to where the help text is located. By default
1286                    this is set to the documentation for the latest released
1287                    BASE version on the BASE web site,
1288                    <ulink
1289                      url="http://base.thep.lu.se/chrome/site/doc/html/index.html">
1290                      http://base.thep.lu.se/chrome/site/doc/html/index.html</ulink>.
1291                   
1292                    If you want the documentation for a specific version you will
1293                    have to setup a site for that yourself and then change the link
1294                    to that site. The documentation is included in the downloaded package
1295                    in the directory <filename>&lt;basedir&gt;/doc/html</filename>.
1296                  </para>
1297                </listitem>
1298              </varlistentry>
1299              <varlistentry>
1300                <term>
1301                  <guilabel>FAQ</guilabel>
1302                </term>
1303                <listitem>
1304                  <para>Where frequently asked questions can be found. Empty by default.</para>
1305                </listitem>
1306              </varlistentry>
1307              <varlistentry>
1308                <term>
1309                  <guilabel>Report a bug</guilabel>
1310                </term>
1311                <listitem>
1312                  <para>
1313                    Where the user could report bugs, feature request or
1314                    perhaps other feedback that concerns the program. As default
1315                    this is set to the feedback section on BASE web site,
1316                    <ulink url="http://base.thep.lu.se/#Feedback">http://base.thep.lu.se/#Feedback</ulink>.
1317                    Note that users must login in order to submit information.
1318                  </para>
1319                </listitem>
1320              </varlistentry>
1321            </variablelist>
1322          </helptext>
1323        </listitem>
1324      </varlistentry>
1325    </variablelist>
1326  </sect1>
1327
1328  <sect1 id="installation_upgrade.migration">
1329    <title>Migration instructions</title>
1330
1331    <caution>
1332      <title>The disclaimer section</title>
1333      <para>
1334        We have made extensive testing of the migration from BASE
1335        version 1.2 (BASE1.2) to BASE version 2 (BASE2). To our
1336        knowledge the migration works but we cannot
1337        guarantee perfect functionality. The migration tool is
1338        supplied as is and usage is done at your risk. We are
1339        committed to solve migration problems at the level of
1340        transferring data from BASE1.2 to BASE2, but
1341        cannot resolve data loss issues in a running BASE2
1342        server due to imperfect
1343        migration. When you start the migration tool you are required
1344        to pass parameter <emphasis>"disclaimer_understood"</emphasis>
1345        to the <filename>migrate_from_1.2.sh</filename>
1346        script. Remember to check that the migration performed well
1347        before you decide to delete your 1.2 installation.
1348      </para>
1349     
1350      <para>
1351        Since BASE 2.6 we no longer actively test or maintain the
1352        migration program. We still accept bug reports and will try
1353        to fix critical bugs, but only if we get help with testing
1354        the fixes before they are released. Supplying a patch for a
1355        bug will increase the chance of getting it fixed.
1356      </para>
1357    </caution>
1358
1359    <para>
1360      Verify that your new BASE installation is up and running before
1361      attempting migration. Preferably try to log in using the root
1362      user through the web interface.
1363    </para>
1364
1365    <para>
1366      Make sure your BASE1.2 runs with the latest
1367      (<emphasis>pristine</emphasis>) schema
1368      version, <emphasis>i.e.,</emphasis> the migration will only
1369      support an unmodified BASE1.2 installation. If you have
1370      an out of date schema version, please upgrade to the latest
1371      schema using BASE1.2 tools before migrating. If you
1372      have made local changes to the BASE1.2 schema you need
1373      to patch the BASE2 schema as well as make proper
1374      changes to the migration program.  If there are added columns to
1375      the reporter table in your BASE1.2 database you need to
1376      transfer the additional information after migration (even if you
1377      modified the BASE2 <filename>extended-properties.xml</filename> file).
1378    </para>
1379
1380    <para>
1381      The behaviour of migration is controlled
1382      through <filename>migration.properties</filename> file (see
1383      <xref linkend="appendix.migrate.properties"/>), but you should
1384      know what you do when you change parameters in this file.
1385    </para>
1386
1387    <para>
1388      Migration can be restarted in one specific case only; If the
1389      migration fails during the RawBioAssayData transfer simply
1390      restart the migration and the script will ask you to verify that
1391      a restart should be attempted. For all other failure points the
1392      migration has to be restarted with an empty database.
1393    </para>
1394
1395    <para>
1396      Migration is performed with the following steps:
1397      <orderedlist>
1398
1399        <listitem>
1400          <para>
1401            To transfer files from BASE1.2 (default migration
1402            behaviour), you must have file system access to BASE1.2
1403            files, <emphasis>i.e.,</emphasis>
1404            the <filename class="directory">/BASE 1.2/data</filename>
1405            directory containing directories
1406            <filename class="directory">rawdata</filename>,
1407            <filename class="directory">uploads</filename>,
1408            <filename class="directory">protocols</filename>, ...
1409          </para>
1410        </listitem>
1411
1412        <listitem>
1413          <para>
1414            Change settings in the file
1415            <filename>&lt;base-dir&gt;/dist/www/WEB-INF/classes/migrate.properties</filename>.
1416            The available options are commented:
1417            <itemizedlist>
1418              <listitem>
1419                <para>
1420                  Modify <emphasis>db1.*</emphasis> parameters to
1421                  match your BASE1.2 installation.
1422                </para>
1423              </listitem>
1424              <listitem>
1425                <para>
1426                  Set <emphasis>userfiles</emphasis> (note, this is
1427                  not the same parameter as
1428                  in <filename>base.config</filename>) to point to the
1429                  directory containing the BASE1.2 files (defined in a
1430                  previous step above).
1431                </para>
1432              </listitem>
1433              <listitem>
1434                <para>
1435                  Set the <emphasis>pluginDir</emphasis> to point to
1436                  the directory where your BASE1.2 plug-ins are
1437                  installed. The default is
1438                  <filename
1439                  class="directory">/usr/local/base/plugins</filename>.
1440                </para>
1441              </listitem>
1442              <listitem>
1443                <para>
1444                  Modify <emphasis>root.password</emphasis>.
1445                </para>
1446              </listitem>
1447              <listitem>
1448                <para>
1449                  Change the <emphasis>deletefiles</emphasis> setting
1450                  wisely. If you
1451                  set <emphasis>deletefiles=yes</emphasis> all BASE1.2
1452                  files will be physically removed when copied to the
1453                  BASE2 server. Leave this options
1454                  as <emphasis>deletefiles=no</emphasis> unless you
1455                  are absolutely sure of what you are doing.
1456                </para>
1457              </listitem>
1458            </itemizedlist>
1459          </para>
1460        </listitem>
1461
1462        <listitem>
1463          <para>
1464            Run migration utility:
1465<programlisting>cd /path_to_base/dist/bin
1466./migrate_from_1.2.sh disclaimer_understood</programlisting>
1467          </para>
1468          <para>
1469            If the migration fails during the RawBioAssayData
1470            transfer you can restart the migration at the point of
1471            failure. Simply restart the migration and the script will
1472            ask you to verify that a restart should be attempted. For
1473            all other failure points the migration has to be restarted
1474            with an empty database.
1475          </para>
1476        </listitem>
1477
1478        <listitem>
1479          <para>
1480            <emphasis>Optional, depends on your BASE1.2 reporter
1481            table.</emphasis> Additional columns (as compared with a
1482            pristine database schema) in the reporter table in the
1483            BASE1.2 schema are not transferred during migration. You
1484            have to perform the transfer manually after
1485            migration. Simply export the reporter information from
1486            BASE1.2, and import the data into the new BASE installation. In BASE1.2: i)
1487            View the reporters, ii) Use `Get as tab-separated text` to
1488            create a tab separated file (right click and save). In
1489            BASE2, to import the file follow the instructions in
1490            <xref linkend="reporters.import"/>.
1491          </para>
1492        </listitem>
1493
1494        <listitem>
1495          <para>
1496            Migration done! Happy BASEing.
1497          </para>
1498        </listitem>
1499
1500      </orderedlist>
1501
1502    </para>
1503
1504  </sect1>      <!-- Migration instructions -->
1505
1506</chapter>
Note: See TracBrowser for help on using the repository browser.