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

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

Fixes #1146: updateindexes.sh should create indexes for foreign keys

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