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

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

Fixes #1113 and #1114: "Broadcast to currently active BASE users" and "Blocking of log in action"

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 55.1 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 4567 2008-10-07 12:13:53Z 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 run <filename>initdb.sh</filename> as
1005<programlisting>./initdb.sh [base_root_login] base_root_password</programlisting>
1006
1007            <important>
1008            <para>
1009            The <emphasis>base_root_login</emphasis> and
1010            <emphasis>base_root_password</emphasis> you use here
1011            is given to the BASE web application root user account.
1012            The <emphasis>base_root_login</emphasis> is optional. If
1013            not specified, <constant>root</constant> is used for
1014            the login.
1015            </para>
1016            </important>
1017            If the initialisation script fail, it is most probably a
1018            problem related to the underlying database. Make sure that
1019            the database accepts network connection and make sure that
1020            <emphasis>db_user</emphasis> has proper credentials.
1021          </para>
1022        </listitem>
1023      </varlistentry>
1024
1025      <varlistentry>
1026        <term>BASE and Tomcat</term>
1027        <listitem>
1028          <para>
1029            Either move the <filename
1030            class="directory">&lt;base-dir&gt;/www</filename> directory
1031            to the Tomcat <filename class="directory">webapps</filename>
1032            directory or create a symbolic link from the Tomcat
1033            <filename class="directory">webapps</filename> directory to
1034            the <filename class="directory">&lt;base-dir&gt;/www</filename>
1035            directory
1036<programlisting>cd /path/to/tomcat/webapps
1037ln -s /path_to_base/www base2</programlisting>
1038          </para>
1039          <para>
1040            If you plan to install extensions you should make sure that
1041            the <filename class="directory">&lt;base-dir&gt;/www/extensions</filename>
1042            directory is writable by the user account Tomcat is running as.
1043          </para>
1044          <para>
1045            Start/restart Tomcat, and try http://hostname:8080/base2
1046            (change <emphasis>hostname</emphasis> to your hostname) in
1047            your favourite browser. The BASE log-in page should appear
1048            after a few seconds.
1049          </para>
1050        </listitem>
1051      </varlistentry>
1052
1053      <varlistentry>
1054        <term>BASE, Apache, and Apache/Tomcat connector</term>
1055        <listitem>
1056          <para>
1057            <emphasis>This step is optional</emphasis>.
1058          </para>
1059          <para>
1060            If you want run the Tomcat server through the Apache web
1061            server, you need to install the Apache version 2 web
1062            server, available
1063            from <ulink
1064            url="http://www.apache.org/">http://www.apache.org/</ulink>,
1065            and a apache-tomcat connector, available
1066            from <ulink
1067            url="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</ulink>.
1068            So, we got you there;-) To be honest, this step is not
1069            really well documented since we previously used SuSE 9.3
1070            on our demo/test server, and apache/tomcat/mod_jk comes
1071            pre-installed. The current server does not use the
1072            apache/tomcat connector. What you need to do is something
1073            like this
1074            <itemizedlist>
1075              <listitem>
1076                Get that Tomcat server running in stand-alone
1077                mode.
1078              </listitem>
1079              <listitem>
1080                Get the Apache 2 server running.
1081              </listitem>
1082              <listitem>
1083                Install mod_jk. Note, different version are used for
1084                apache 1.3 and 2. In SuSE 9.3 this step is done by
1085                installing <filename>mod_jk-ap20</filename>.
1086              </listitem>
1087              <listitem>
1088                Create a <filename>workers.properties</filename> file
1089                in the
1090                Tomcat <filename class="directory">base</filename>
1091                directory (commonly copied from a template).
1092              </listitem>
1093              <listitem>
1094                Create a <filename>jk.conf</filename> file in the
1095                apache <filename class="directory">conf</filename>
1096                directory (commonly copied from a template), and make
1097                sure that <emphasis>jk</emphasis> is added to the
1098                modules to be loaded when apache starts.
1099              </listitem>
1100              <listitem>
1101                In <filename>jk.conf</filename> add the lines below
1102                and change paths appropriately.
1103<programlisting># The following lines makes apache aware of the location of
1104# the /base2 context
1105Alias /base2 "/srv/www/tomcat6/base/webapps/base2"
1106&lt;Directory "/srv/www/tomcat6/base/webapps/base2"&gt;
1107Options Indexes FollowSymLinks
1108allow from all
1109&lt;/Directory&gt;
1110# The following lines mounts all base2 jsp files to Tomcat
1111JkMount /base2 ajp13
1112JkMount /base2/* ajp13
1113# The following lines prohibits users from directly accessing WEB-INF
1114&lt;Location "/base2/WEB-INF/"&gt;
1115AllowOverride None
1116deny from all
1117&lt;/Location&gt;</programlisting>
1118              </listitem>
1119            </itemizedlist>
1120            You must restart the Apache and the Tomcat server after above steps.
1121          </para>
1122        </listitem>
1123      </varlistentry>
1124
1125      <varlistentry>
1126        <term>Setup done!</term>
1127        <listitem>
1128          <para>
1129            Happy BASEing. Now you can log on to your BASE server as
1130            user <emphasis>root</emphasis> (use
1131            the <emphasis>base_root_password</emphasis> from the
1132            database initialization step above). You should begin with
1133            creating a couple user accounts, for more information on
1134            how to create user accounts please refer to
1135            <xref linkend="user_administration"/>.
1136          </para>
1137          <para>
1138            If you are planning to perform a migration of data from
1139            BASE version 1.2.x please perform the steps in
1140            <xref linkend="installation_upgrade.migration"/> before
1141            doing anything else with your new BASE installation.
1142          </para>
1143        </listitem>
1144      </varlistentry>
1145
1146    </variablelist>
1147
1148  </sect1>      <!-- Installation instructions -->
1149
1150  <sect1 id="installation_upgrade.serverconfigurations">
1151    <title>Server configurations</title>
1152    <para>
1153      Some server configurations can be done when the installation process is finished and
1154      BASE is up and running. Log into BASE with administration rights and then
1155      open the configuration dialog from menu
1156      <menuchoice>
1157        <guimenu>Administrate</guimenu>
1158        <guimenuitem>Server settings</guimenuitem>
1159      </menuchoice>.
1160      Each tab in the configuration dialog-window is described below.
1161    </para>
1162    <variablelist>
1163      <varlistentry>
1164        <term>
1165          <guilabel>File transfer</guilabel>
1166        </term>
1167        <listitem>
1168          <helptext external_id="serverconfig.filetransfer" title="File transfer rate">
1169            <variablelist>
1170              <varlistentry>
1171                <term><guilabel>Max transfer rate</guilabel></term>
1172                <listitem>
1173                  <para>
1174                    This is a limit of how many bytes of data that should be
1175                    transferred per second when uploading files to BASE. Prefixes
1176                    like k, M or G can be used for larger values, just like
1177                    described in the tab. The limit is per ongoing upload
1178                    and the default value is 100MB/s.
1179                  </para>
1180                </listitem>
1181              </varlistentry>
1182              <varlistentry>
1183                <term><guilabel>Unlimited</guilabel></term>
1184                <listitem>
1185                  <para>
1186                    Check this to not limit the transfer rate. In this case, the
1187                    Internet connection of the server is the limit.
1188                  </para>
1189                </listitem>
1190              </varlistentry>
1191            </variablelist>
1192          </helptext>
1193        </listitem>
1194      </varlistentry>
1195      <varlistentry>
1196        <term>
1197          <guilabel>About</guilabel>
1198        </term>
1199        <listitem>
1200          <helptext external_id="serverconfig.about"
1201            title="Information about the server">
1202            <variablelist>
1203              <varlistentry>
1204                <term><guilabel>Administrator name</guilabel></term>
1205                <listitem>
1206                  <para>
1207                    Name of the responsible administrator. The name is displayed
1208                    at the bottom of each page in BASE and in the about-dialog.
1209                  </para>
1210                </listitem>
1211              </varlistentry>
1212              <varlistentry>
1213                <term><guilabel>Administrator email</guilabel></term>
1214                <listitem>
1215                  <para>
1216                    An email which the administrator can be contacted on. The
1217                    administrator name, visible at the bottom of each page, will
1218                    be linked to this email address.
1219                  </para>
1220                </listitem>
1221              </varlistentry>
1222              <varlistentry>
1223                <term><guilabel>About</guilabel></term>
1224                <listitem>
1225                  <para>
1226                    Text written in this field is displayed in the
1227                    <guilabel>About this server</guilabel> section on the login
1228                    page and in the about-dialog window. We recommend changing the
1229                    default Latin text to something meaningful, or remove it
1230                    to hide the section completely.
1231                  </para>
1232                </listitem>
1233              </varlistentry>
1234            </variablelist>
1235          </helptext>
1236        </listitem>
1237      </varlistentry>
1238      <varlistentry>
1239        <term>
1240          <guilabel>Get account</guilabel>
1241        </term>
1242        <listitem>
1243          <helptext external_id="serverconfig.getaccount"
1244            title="Instructions to get an account">
1245            <para>
1246              A description what a none-registered user should do to get
1247              an account on the particular BASE-server. This text is linked
1248              to the <guilabel>Get an account!</guilabel> link on the login
1249              page. We recommend that the Latin text is replaced with some useful
1250              information, or that it is removed to hide the link.
1251            </para>
1252          </helptext>
1253        </listitem>
1254      </varlistentry>
1255      <varlistentry>
1256        <term>
1257          <guilabel>Forgotten password</guilabel>
1258        </term>
1259        <listitem>
1260          <helptext external_id="serverconfig.password"
1261            title="Instructions when password is forgotten.">
1262            <para>
1263              A description what an user should do if the password is forgotten.
1264              This text is linked
1265              to the <guilabel>Forgot your password?</guilabel> link on the login
1266              page. We recommend that the Latin text is replaced with some useful
1267              information, or that it is removed to hide the link.
1268            </para>
1269          </helptext>
1270        </listitem>
1271      </varlistentry>
1272      <varlistentry>
1273        <term>
1274          <guilabel>Links</guilabel>
1275        </term>
1276        <listitem>
1277          <helptext external_id="serverconfig.links" title="Configurable links">
1278            <para>
1279              External configurable link-types inside BASE.
1280              <note>
1281                <para>
1282                  Only link-types that have been set will be visible in the web
1283                  client.
1284                </para>
1285              </note>
1286            </para>
1287            <variablelist>
1288              <varlistentry>
1289                <term><guilabel>Help</guilabel></term>
1290                <listitem>
1291                  <para>
1292                    Links to where the help text is located. By default
1293                    this is set to the documentation for the latest released
1294                    BASE version on the BASE web site,
1295                    <ulink
1296                      url="http://base.thep.lu.se/chrome/site/doc/html/index.html">
1297                      http://base.thep.lu.se/chrome/site/doc/html/index.html</ulink>.
1298                   
1299                    If you want the documentation for a specific version you will
1300                    have to setup a site for that yourself and then change the link
1301                    to that site. The documentation is included in the downloaded package
1302                    in the directory <filename>&lt;basedir&gt;/doc/html</filename>.
1303                  </para>
1304                </listitem>
1305              </varlistentry>
1306              <varlistentry>
1307                <term>
1308                  <guilabel>FAQ</guilabel>
1309                </term>
1310                <listitem>
1311                  <para>Where frequently asked questions can be found. Empty by default.</para>
1312                </listitem>
1313              </varlistentry>
1314              <varlistentry>
1315                <term>
1316                  <guilabel>Report a bug</guilabel>
1317                </term>
1318                <listitem>
1319                  <para>
1320                    Where the user could report bugs, feature request or
1321                    perhaps other feedback that concerns the program. As default
1322                    this is set to the feedback section on BASE web site,
1323                    <ulink url="http://base.thep.lu.se/#Feedback">http://base.thep.lu.se/#Feedback</ulink>.
1324                    Note that users must login in order to submit information.
1325                  </para>
1326                </listitem>
1327              </varlistentry>
1328            </variablelist>
1329          </helptext>
1330        </listitem>
1331      </varlistentry>
1332    </variablelist>
1333   
1334    <sect2 id="installation_upgrade.broadcast">
1335      <title>Sending a broadcast message to logged in users</title>
1336
1337      <para>
1338        It is possible to send a message to all logged in user.
1339        Open the
1340        <menuchoice>
1341          <guimenu>Administrate</guimenu>
1342          <guimenuitem>Broadcast message</guimenuitem>
1343        </menuchoice> dialog box.
1344      </para>
1345     
1346      <helptext external_id="broadcast.message" title="Broadcast message">
1347        <para>
1348        This dialog allows you to specify a message that is sent to all
1349        logged in users as well as on the login form. It is also possible
1350        to "disable" login.
1351        </para>
1352        <variablelist>
1353        <varlistentry>
1354          <term><guilabel>Title</guilabel></term>
1355          <listitem>
1356            <para>
1357            The title of the message. It should be a short and consice to
1358            avoid confusion. The title will be displayed on a lot of places
1359            and a user may have to click on it to read the more detailed
1360            message.
1361            </para>
1362          </listitem>
1363        </varlistentry>
1364        <varlistentry>
1365          <term><guilabel>Disable login</guilabel></term>
1366          <listitem>
1367            <para>
1368            Mark this checkbox to try to prevent new users from logging in. To
1369            avoid problems that can be caused by blocking the server admin out,
1370            the login is not completely, disabled. Any user can still login but
1371            only after by-passing several warnings.
1372            </para>
1373          </listitem>
1374        </varlistentry>
1375        <varlistentry>
1376          <term><guilabel>Message</guilabel></term>
1377          <listitem>
1378            <para>
1379            If needed, a longer message giving more information. Users may
1380            have to click on a link to be able to see the complete message.
1381            </para>
1382          </listitem>
1383        </varlistentry>
1384        </variablelist>
1385       
1386        <note>
1387          The message will be enabled until it is manually removed by saving
1388          an empty form, or until the Tomcat server is restarted. Since the
1389          message is only kept in memory, a restart will always remove it.
1390        </note>
1391     
1392      </helptext>
1393     
1394    </sect2>
1395   
1396  </sect1>
1397
1398  <sect1 id="installation_upgrade.migration">
1399    <title>Migration instructions</title>
1400
1401    <caution>
1402      <title>The disclaimer section</title>
1403      <para>
1404        We have made extensive testing of the migration from BASE
1405        version 1.2 (BASE1.2) to BASE version 2 (BASE2). To our
1406        knowledge the migration works but we cannot
1407        guarantee perfect functionality. The migration tool is
1408        supplied as is and usage is done at your risk. We are
1409        committed to solve migration problems at the level of
1410        transferring data from BASE1.2 to BASE2, but
1411        cannot resolve data loss issues in a running BASE2
1412        server due to imperfect
1413        migration. When you start the migration tool you are required
1414        to pass parameter <emphasis>"disclaimer_understood"</emphasis>
1415        to the <filename>migrate_from_1.2.sh</filename>
1416        script. Remember to check that the migration performed well
1417        before you decide to delete your 1.2 installation.
1418      </para>
1419     
1420      <para>
1421        Since BASE 2.6 we no longer actively test or maintain the
1422        migration program. We still accept bug reports and will try
1423        to fix critical bugs, but only if we get help with testing
1424        the fixes before they are released. Supplying a patch for a
1425        bug will increase the chance of getting it fixed.
1426      </para>
1427    </caution>
1428
1429    <para>
1430      Verify that your new BASE installation is up and running before
1431      attempting migration. Preferably try to log in using the root
1432      user through the web interface.
1433    </para>
1434
1435    <para>
1436      Make sure your BASE1.2 runs with the latest
1437      (<emphasis>pristine</emphasis>) schema
1438      version, <emphasis>i.e.,</emphasis> the migration will only
1439      support an unmodified BASE1.2 installation. If you have
1440      an out of date schema version, please upgrade to the latest
1441      schema using BASE1.2 tools before migrating. If you
1442      have made local changes to the BASE1.2 schema you need
1443      to patch the BASE2 schema as well as make proper
1444      changes to the migration program.  If there are added columns to
1445      the reporter table in your BASE1.2 database you need to
1446      transfer the additional information after migration (even if you
1447      modified the BASE2 <filename>extended-properties.xml</filename> file).
1448    </para>
1449
1450    <para>
1451      The behaviour of migration is controlled
1452      through <filename>migration.properties</filename> file (see
1453      <xref linkend="appendix.migrate.properties"/>), but you should
1454      know what you do when you change parameters in this file.
1455    </para>
1456
1457    <para>
1458      Migration can be restarted in one specific case only; If the
1459      migration fails during the RawBioAssayData transfer simply
1460      restart the migration and the script will ask you to verify that
1461      a restart should be attempted. For all other failure points the
1462      migration has to be restarted with an empty database.
1463    </para>
1464
1465    <para>
1466      Migration is performed with the following steps:
1467      <orderedlist>
1468
1469        <listitem>
1470          <para>
1471            To transfer files from BASE1.2 (default migration
1472            behaviour), you must have file system access to BASE1.2
1473            files, <emphasis>i.e.,</emphasis>
1474            the <filename class="directory">/BASE 1.2/data</filename>
1475            directory containing directories
1476            <filename class="directory">rawdata</filename>,
1477            <filename class="directory">uploads</filename>,
1478            <filename class="directory">protocols</filename>, ...
1479          </para>
1480        </listitem>
1481
1482        <listitem>
1483          <para>
1484            Change settings in the file
1485            <filename>&lt;base-dir&gt;/dist/www/WEB-INF/classes/migrate.properties</filename>.
1486            The available options are commented:
1487            <itemizedlist>
1488              <listitem>
1489                <para>
1490                  Modify <emphasis>db1.*</emphasis> parameters to
1491                  match your BASE1.2 installation.
1492                </para>
1493              </listitem>
1494              <listitem>
1495                <para>
1496                  Set <emphasis>userfiles</emphasis> (note, this is
1497                  not the same parameter as
1498                  in <filename>base.config</filename>) to point to the
1499                  directory containing the BASE1.2 files (defined in a
1500                  previous step above).
1501                </para>
1502              </listitem>
1503              <listitem>
1504                <para>
1505                  Set the <emphasis>pluginDir</emphasis> to point to
1506                  the directory where your BASE1.2 plug-ins are
1507                  installed. The default is
1508                  <filename
1509                  class="directory">/usr/local/base/plugins</filename>.
1510                </para>
1511              </listitem>
1512              <listitem>
1513                <para>
1514                  Modify <emphasis>root.password</emphasis>.
1515                </para>
1516              </listitem>
1517              <listitem>
1518                <para>
1519                  Change the <emphasis>deletefiles</emphasis> setting
1520                  wisely. If you
1521                  set <emphasis>deletefiles=yes</emphasis> all BASE1.2
1522                  files will be physically removed when copied to the
1523                  BASE2 server. Leave this options
1524                  as <emphasis>deletefiles=no</emphasis> unless you
1525                  are absolutely sure of what you are doing.
1526                </para>
1527              </listitem>
1528            </itemizedlist>
1529          </para>
1530        </listitem>
1531
1532        <listitem>
1533          <para>
1534            Run migration utility:
1535<programlisting>cd /path_to_base/dist/bin
1536./migrate_from_1.2.sh disclaimer_understood</programlisting>
1537          </para>
1538          <para>
1539            If the migration fails during the RawBioAssayData
1540            transfer you can restart the migration at the point of
1541            failure. Simply restart the migration and the script will
1542            ask you to verify that a restart should be attempted. For
1543            all other failure points the migration has to be restarted
1544            with an empty database.
1545          </para>
1546        </listitem>
1547
1548        <listitem>
1549          <para>
1550            <emphasis>Optional, depends on your BASE1.2 reporter
1551            table.</emphasis> Additional columns (as compared with a
1552            pristine database schema) in the reporter table in the
1553            BASE1.2 schema are not transferred during migration. You
1554            have to perform the transfer manually after
1555            migration. Simply export the reporter information from
1556            BASE1.2, and import the data into the new BASE installation. In BASE1.2: i)
1557            View the reporters, ii) Use `Get as tab-separated text` to
1558            create a tab separated file (right click and save). In
1559            BASE2, to import the file follow the instructions in
1560            <xref linkend="reporters.import"/>.
1561          </para>
1562        </listitem>
1563
1564        <listitem>
1565          <para>
1566            Migration done! Happy BASEing.
1567          </para>
1568        </listitem>
1569
1570      </orderedlist>
1571
1572    </para>
1573
1574  </sect1>      <!-- Migration instructions -->
1575
1576</chapter>
Note: See TracBrowser for help on using the repository browser.