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

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

Fixes #1168: Require UTF-8 to be used as database character set

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