source: trunk/doc/src/docbook/admin/installation.xml @ 6862

Last change on this file since 6862 was 6862, checked in by Nicklas Nordborg, 7 years ago

References #1926: Switch to Java 8

Updated installation documentation.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 60.6 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.xml 6862 2015-04-15 11:01:57Z nicklas $
7
8  Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
9  Copyright (C) 2008 Jari Häkkinen, Nicklas Nordborg, Martin Svensson
10  Copyright (C) 2009 Jari Häkkinen, Nicklas Nordborg
11  Copyright (C) 2010, 2011, 2012 Nicklas Nordborg
12  Copyright (C) 2013 Jari Häkkinen, Nicklas Nordborg
13
14  This file is part of BASE - BioArray Software Environment.
15  Available at http://base.thep.lu.se/
16
17  BASE is free software; you can redistribute it and/or
18  modify it under the terms of the GNU General Public License
19  as published by the Free Software Foundation; either version 3
20  of the License, or (at your option) any later version.
21
22  BASE is distributed in the hope that it will be useful,
23  but WITHOUT ANY WARRANTY; without even the implied warranty of
24  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
25  GNU General Public License for more details.
26
27  You should have received a copy of the GNU General Public License
28  along with BASE. If not, see <http://www.gnu.org/licenses/>.
29-->
30
31<chapter id="installation">
32
33  <title>Installation and upgrade instructions</title>
34
35  <note>
36    <para>
37    These instructions apply only to the BASE release which this
38    document is a part of. The instructions here assume
39    that <ulink url="http://tomcat.apache.org/">Apache Tomcat 7</ulink> is used
40    on the server side. Other servlet engines may work but we only
41    test with Tomcat.
42    </para>
43  </note>
44
45  <sect1 id="installation.upgrade">
46    <title>Upgrade instructions</title>
47
48    <important id="installation.upgrade.important">
49      <title>Important information for upgrading to BASE 3.6</title>
50      <para>
51        This section list some important information that may or may not
52        apply when upgrading from the <emphasis>previous</emphasis> BASE
53        release to the current release (eg. 3.5 to 3.6). If you are
54        upgrading from a BASE installation that is older (3.0-3.4)
55        you should also read <xref linkend="appendix.update_warnings" />.
56      </para>
57     
58      <bridgehead>Update to Java 8</bridgehead>
59      <para>
60        BASE will no longer run with Java 7. Unless you have already
61        updated to Java 8 you should do so before updating to BASE 3.6.
62        Note that BASE 3.5 also works with both Java 7 and 8 so the Java
63        update can be made ahead of time.
64      </para>
65   
66    </important>
67   
68    <para>
69      As always, backup your database before attempting an
70      upgrade. The BASE team performs extensive testing before
71      releasing a new version of BASE but there are always a
72      possibility for unexpected events during upgrades. In upgrades
73      requiring a change in the underlying database there is no
74      (supported) way to revert to a previous version of BASE using
75      BASE tools, you need to use your backup for this use case.
76    </para>
77
78    <para>
79      The strategy here is to install the new BASE release to another
80      directory than the one in use. This requires transfer of
81      configuration settings to the new install but more on that
82      below.
83    </para>
84
85    <variablelist>
86      <varlistentry>
87        <term>Shut down the Tomcat server</term>
88        <listitem>
89          <para>
90            If the BASE application is not shut down already, it is
91            time to do it now. Do something like <command>sudo
92            /etc/init.d/tomcat7.0 stop</command>
93          </para>
94         
95          <tip>
96            <title>Notify logged in users!</title>
97            <para>
98              If there are users logged in to your BASE server, it may
99              be nice of you to notify them a few minutes prior to shutting
100              down the BASE server. See <xref linkend="installation.broadcast" />.
101            </para>
102          </tip>
103        </listitem>
104      </varlistentry>
105
106      <varlistentry>
107        <term>Rename your current server</term>
108        <listitem>
109          <para>
110            Rename your current BASE installation <command>mv
111              /path/to/base /path/to/base_old</command>.
112          </para>
113        </listitem>
114      </varlistentry>
115
116      <varlistentry>
117        <term>Download and unpack BASE</term>
118        <listitem>
119          <para>
120            There are several ways to download BASE. Please refer to
121            section <xref linkend="resources.home_page.download"/> for
122            information on downloading BASE, and select the item
123            matching your download option:
124          </para>
125
126          <variablelist>
127            <varlistentry>
128              <term><emphasis>Pre-compiled package</emphasis></term>
129              <listitem>
130                <para>
131                  If you selected to download a pre-compiled package,
132                  unpack the downloaded file with <command>tar zxpf
133                  base-...tar.gz</command>.
134                </para>
135              </listitem>
136            </varlistentry>
137
138            <varlistentry>
139              <term><emphasis>Source package</emphasis></term>
140              <listitem>
141                <para>
142                  If you selected to download a source package, unpack
143                  the downloaded file with <command>tar zxpf
144                  base-...src.tar.gz</command>. Change to the new
145                  directory, and issue <command>ant
146                  package.bin</command>. This will create a binary
147                  package in the current directory. Unpack this new
148                  package (outside of the source file hierarchy).
149                </para>
150              </listitem>
151            </varlistentry>
152
153            <varlistentry>
154              <term><emphasis>Subversion checkout</emphasis></term>
155              <listitem>
156                <para>
157                  This option is for advanced users only and is not
158                  covered here. Please refer to
159                  <ulink url="http://base.thep.lu.se/wiki/BuildingBase" /> for information on
160                  this download option.
161                </para>
162              </listitem>
163            </varlistentry>
164
165          </variablelist>
166        </listitem>
167
168      </varlistentry>
169
170      <varlistentry>
171        <term>Transfer files and settings</term>
172        <listitem>
173          <para>
174            Settings from the previous installation must be
175            transferred to the new installation. This is most easily
176            done by comparing the configuration files from the
177            previous install with the new files. Do not just copy the
178            old files to the new install since new options may have
179            appeared.
180          </para>
181          <para>
182            In the main BASE configuration file,
183            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>,
184            fields that needs to be transferred are usually
185            <emphasis>db.username</emphasis>,
186            <emphasis>db.password</emphasis>,
187            and <emphasis>userfiles</emphasis>.
188          </para>
189          <para>
190            Local settings in the raw data
191            tables, <filename>&lt;base-dir&gt;/www/WEB-INF/classes/raw-data-types.xml</filename>,
192            may need to be transferred. This also includes all files in
193            the <filename>&lt;base-dir&gt;/www/WEB-INF/classes/raw-data-types</filename> and
194            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/extended-properties</filename>
195            directories.
196          </para>
197        </listitem>
198      </varlistentry>
199
200      <varlistentry>
201        <term>Updating database schema</term>
202        <listitem>
203          <para>
204            It is recommended that you also perform an update of your
205            database schema.  Running the update scripts are not
206            always necessary when upgrading BASE, but the running the
207            update scripts are safe even in cases when there is no
208            need to run them. Change directory
209            to <filename
210            class="directory">&lt;base-dir&gt;/bin/</filename> and issue
211<programlisting>
212sh ./updatedb.sh [base_root_login] <emphasis>base_root_password</emphasis>
213sh ./updateindexes.sh
214</programlisting>
215            where <emphasis>base_root_login</emphasis> is the login
216            for the root user and <emphasis>base_root_password</emphasis> is the
217            password. The login is optional. If not specified,
218            <constant>root</constant> is used as the login.
219          </para>
220        </listitem>
221      </varlistentry>
222
223      <varlistentry>
224        <term>Start Tomcat</term>
225        <listitem>
226          <para>
227            Start the Tomcat server: <command>sudo
228              /etc/init.d/tomcat7.0 start</command>
229          </para>
230        </listitem>
231      </varlistentry>
232
233    </variablelist>
234
235    <para>
236      Done! Upgrade of BASE is finished.
237    </para>
238
239  </sect1>      <!-- Upgrade instructions -->
240
241  <sect1 id="installation.main">
242    <title>Installation instructions</title>
243
244    <variablelist>
245
246      <varlistentry>
247        <term>Java</term>
248        <listitem>
249          <para>
250            Download and install Java SE 8, available from
251            <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html" />.
252            You can select either the JDK or the JRE version.
253          </para>
254         
255          <note>
256            <para>
257            As of BASE 3.6 only Java SE 8 is supported. Java SE 7
258            or lower is not supported.
259            </para>
260          </note>
261
262        </listitem>
263      </varlistentry>
264
265      <varlistentry>
266        <term>Set up an SQL database</term>
267        <listitem>
268          <para>
269            BASE
270            utilise <ulink
271            url="http://www.hibernate.org/">Hibernate</ulink> for
272            object persistence to a relational database. Hibernate
273            supports many database engines, but so far we only work
274            with <ulink url="http://www.mysql.com">MySQL</ulink>
275            and <ulink
276            url="http://www.postgresql.org/">PostgreSQL</ulink>.
277          </para>
278
279          <variablelist>
280            <varlistentry>
281              <term>MySQL</term>
282              <listitem>
283                <para>
284                  Download and install MySQL (tested with version
285                  5.5), available from
286                  <ulink url="http://www.mysql.com/" />. You need to
287                  be able to connect to the server over TCP, so
288                  the <emphasis>skip-networking</emphasis> option
289                  must <command>not</command> be used. The InnoDB
290                  table engine is also needed, so do not disable them
291                  (not that you would) but you may want to tune the
292                  InnoDB behaviour before creating BASE
293                  databases. BASE comes pre-configured for MySQL so
294                  there is no need to change database settings in the
295                  BASE configuration files.
296                </para>
297              </listitem>
298            </varlistentry>
299            <varlistentry>
300              <term>PostgreSQL</term>
301              <listitem>
302                <para>
303                  PostgreSQL 9.3 seems to be working very well with
304                  BASE and Hibernate. Download and install PostgreSQL,
305                  available from
306                  <ulink url="http://www.postgresql.org/" />. You must edit
307                  your <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
308                  file. Uncomment the settings for PostgreSQL and
309                  comment out the settings for MySQL.
310                </para>
311              </listitem>
312            </varlistentry>
313          </variablelist>
314
315        </listitem>
316      </varlistentry>
317
318      <varlistentry id="installation.main.database">
319        <term>BASE (database engine)</term>
320        <listitem>
321          <para>
322            The database names (base2 and base2dynamic are used here),
323            the <emphasis>db_user</emphasis>, and the
324            <emphasis>db_password</emphasis> can be changed during the
325            creation of the databases. It is recommended to change the
326            <emphasis>db_password</emphasis>, the other changes are
327            optional and can be made if desired. The database names,
328            the <emphasis>db_user</emphasis>, and the
329            <emphasis>db_password</emphasis> are needed below when
330            configuring BASE.
331          </para>
332          <note>
333            Note that the <emphasis>db_user</emphasis> name and
334            <emphasis>db_password</emphasis> set here is used
335            internally by BASE in communication with the database and
336            is never used to log on to the BASE application.
337          </note>
338          <important>
339            <title>The database must use the UTF-8 character set</title>
340            <para>
341              Otherwise there will be a problem with storing values
342              that uses characters outside the normal Latin1 range,
343              for example unit-related such as µ (micro) and Ω (ohm).
344            </para>
345          </important>
346          <variablelist>
347            <varlistentry>
348              <term>MySQL</term>
349              <listitem>
350                <para>
351                  Create a new database for BASE, and add a
352                  <emphasis>db_user</emphasis> with at least
353                  <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
354                  <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
355                  <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
356                  <emphasis>INDEX</emphasis>,
357                  and <emphasis>ALTER</emphasis> permission for the
358                  new database. To do this, connect to your MySQL
359                  server and issue the next lines:
360<programlisting>CREATE DATABASE base2 DEFAULT CHARACTER SET utf8;
361CREATE DATABASE base2dynamic DEFAULT CHARACTER SET utf8;
362GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
363GRANT ALL ON base2dynamic.* TO db_user@localhost;</programlisting>
364                </para>             
365                <para>
366                  If you download BASE (instructions below) you find a file
367                  <filename>&lt;base-dir&gt;/misc/sql/createdb.mysql.sql</filename>
368                  that contains the above statements and can be used
369                  by the <filename>mysql</filename> command-line tool
370                  (remember to edit the <emphasis>db_user</emphasis>,
371                  <emphasis>db_password</emphasis>, and the database
372                  names in the script file before executing the
373                  command): <command>mysql -uroot -p &lt;
374                  &lt;base-dir&gt;/misc/sql/createdb.mysql.sql</command>. The
375                  header in the script file contains further
376                  information about the script.
377                </para>
378              </listitem>
379            </varlistentry>
380            <varlistentry>
381              <term>PostgreSQL</term>
382              <listitem>
383                <para>
384                  Create a new database for BASE, and add a
385                  <emphasis>db_user</emphasis> with the proper
386                  privileges. To do this, log in as your PostgreSQL
387                  user and issue these lines (omit comments):
388<programlisting>createuser db_user -P
389  # this will prompt for an password for the new user, and issue two
390  # more question that should be answered with character 'n' for no.
391createdb --owner db_user --encoding UTF8 base2
392psql base2
393  # this will start the psql command line tool. Issue the next line
394  # within the tool and quit with a '\q'.
395CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting>
396
397                  If you download BASE (instructions below) you find a file
398                  <filename>&lt;base-dir&gt;/misc/sql/createdb.postgresql.sql</filename>
399                  that contains the above statements and can be used
400                  by the <filename>psql</filename> command-line tool:
401                  <command>psql -f
402                  &lt;base-dir&gt;/misc/sql/createdb.posgres.sql
403                  template1</command> The header in the script file
404                  contains further information about the script.
405                </para>
406              </listitem>
407            </varlistentry>
408          </variablelist>
409        </listitem>
410      </varlistentry>
411
412      <varlistentry>
413        <term>BASE (download and unpacking)</term>
414        <listitem>
415          <para>
416            <ulink
417            url="http://base.thep.lu.se/wiki/DownloadPage">Download
418            BASE</ulink> and unpack the downloaded file,
419            i.e. <command>tar zxpf base-...tar.gz</command>. If you
420            prefer to have the bleeding edge version of BASE, perform
421            a checkout of the source from the subversion repository
422            (subversion checkout instructions at
423            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
424            trac site</ulink>).
425          </para>
426          <para>
427            If you choose to download the binary package, skip to the
428            next item. The rest of us, read on and compile BASE. If
429            you downloaded a source distribution, unpack the
430            downloaded file <command>tar zxpf
431            base-...src.tar.gz</command>, or you may have performed a
432            subversion checkout.  Change to the 'root' base2
433            directory, and issue <command>ant
434            package.bin</command>. This will create a binary package
435            in the base2 'root' directory. Unpack this new package
436            (outside of the source file hierarchy), and from now on
437            the instructions are the same irrespective where you got
438            the binary package.
439          </para>
440          <para>
441            <emphasis>This section is intended for advanced users and
442              programmers only. In cases when you want to change the
443              BASE code and try out personalised features it may be
444              advantageous to run the tweaked BASE server against the
445              development tree. Instructions on how to accomplish this
446              is available in the
447              <ulink
448              url="http://base.thep.lu.se/wiki/BuildingBase">building
449              BASE document</ulink>. When you return back after
450              compiling in the subversion tree you can follow the
451              instruction here (with obvious changes to
452              paths).</emphasis>
453          </para>
454        </listitem>
455      </varlistentry>
456
457      <varlistentry>
458        <term>BASE (file storage setup)</term>
459        <listitem>
460          <para>
461            An area for file storage must be setup. Create an empty
462            directory in a proper location in your file system. Set
463            the owner of the created directory to the user the Tomcat
464            server will be running as. Tomcat server set up
465            instructions will follow below. Remember this location for
466            later use. The default location is <filename>/usr/local/base2/files</filename>.
467          </para>
468        </listitem>
469      </varlistentry>
470     
471      <varlistentry>
472        <term>BASE (plug-in setup)</term>
473        <listitem>
474          <para>
475            An area for plug-in and extensions installation must be setup.
476            Create an empty directory in a proper location in your file system,
477            and make sure that the user that the Tomcat
478            server will be running as has read permission in this
479            directory. Tomcat server set up instructions will follow
480            below. Remember this location for
481            later use. The default location is <filename>/usr/local/base2/plugins</filename>.
482          </para>
483        </listitem>
484      </varlistentry>
485
486      <varlistentry id="installation.main.configuration">
487        <term>BASE (configuration)</term>
488        <listitem>
489          <para>
490            Basic BASE configuration is done in
491            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>:
492            <itemizedlist>
493              <listitem>
494                Uncomment the database engine section that match your setup.
495              </listitem>
496              <listitem>
497                Modify the <emphasis>db.url</emphasis>,
498                <emphasis>db.dynamic.catalog</emphasis>,
499                <emphasis>db.username</emphasis>,
500                and <emphasis>db.password</emphasis> settings to match
501                your choice above. (<emphasis>database host and
502                database name (e.g. base2)</emphasis>,
503                <emphasis>e.g. base2dynamic</emphasis>,
504                <emphasis>db_user</emphasis>, and
505                <emphasis>db_password</emphasis>, respectively.)
506              </listitem>
507              <listitem>
508                Modify the <emphasis>userfiles</emphasis> setting to
509                match your choice in file storage setup above.
510              </listitem>
511              <listitem>
512                Modify the <emphasis>plugins.dir</emphasis> setting to
513                match your choice in plug-in setup above.
514              </listitem>
515            </itemizedlist>
516            See the <xref linkend="appendix.base.config"/> for more
517            information about the settings in
518            the <filename>base.config</filename> file.
519          </para>
520          <para>
521            <emphasis>Optional but recommended.</emphasis> You may want
522            to modify extended properties to fit your needs. Extended
523            properties are defined in
524            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/extended-properties.xml</filename>.
525            There is an
526            administrator <ulink
527            url="http://base.thep.lu.se/chrome/site/doc/historical/admin/extended-properties.html">document
528            discussing extended properties</ulink> available. If you
529            plan to perform a migration of a BASE version 1.2 database you
530            should probably not remove any extended properties
531            columns (this is not tested so the outcome is currently
532            undefined). However, adding columns does not affect
533            migration.
534          </para>
535        </listitem>
536      </varlistentry>
537
538      <varlistentry>
539        <term>BASE (database initialisation)</term>
540        <listitem>
541          <para>
542            Change directory to
543            <filename class="directory">&lt;base-dir&gt;/bin</filename>
544            and execute the following commands:
545        <programlisting>
546sudo ./initdb.sh [base_root_login] base_root_password
547./updateindexes.sh
548</programlisting>
549          </para>
550
551          <para>
552            In the first command sudo is required because a file will
553            be created in the directory defined by
554            <emphasis>userfiles</emphasis> above. If the directory is
555            writable by you then sudo is not needed.
556          </para>
557
558          <para>
559            The second command is important since
560            the Hibernate database initialisation utility is not always
561            able to create all required indexes. In some cases, Hibernate
562            will also create a new index, even if one already exists.
563            The command ensures that missing indexes are created and
564            that duplicates are removed. BASE will work without the
565            indexes but performance is impaired.
566          </para>
567
568            <important>
569            <para>
570            The <emphasis>base_root_login</emphasis> and
571            <emphasis>base_root_password</emphasis> you use here
572            is given to the BASE web application root user account.
573            The <emphasis>base_root_login</emphasis> is optional. If
574            not specified, <constant>root</constant> is used for
575            the login.
576            </para>
577            </important>
578
579          <para>
580            If the initialisation script fails, it is probably a
581            problem related to the underlying database. Make sure that
582            the database accepts network connection and make sure that
583            <emphasis>db_user</emphasis> has proper credentials. You
584            may also get a <emphasis>Permission denied</emphasis> on
585            file <filename>extension-settings.xml</filename> if you do
586            not have write permission to the directory defined by
587            variable <emphasis>userfiles</emphasis> in file
588            <filename>base.config</filename>. If the initialisation
589            fails on <filename>extension-settings.xml</filename> you
590            must drop the database and recreate the database as
591            described in <xref linkend="installation.main.database"/>.
592          </para>
593        </listitem>
594      </varlistentry>
595
596      <varlistentry>
597        <term>Tomcat</term>
598        <listitem>
599          <para>
600            Download and install Apache Tomcat 8 (recommended) or
601            Apache Tomcat 7 available from <ulink url="http://tomcat.apache.org" />.
602          </para>
603
604          <important>
605            <para>
606              As of BASE 3.5, we are recommending Tomcat 8. Support for Tomcat
607              7 will be removed in BASE 3.6.
608            </para>
609          </important>
610
611          <para>
612            There are a few configuration options that are needed to
613            make Tomcat work properly with BASE. The options are set in the
614            <code>CATALINA_OPTS</code> environment variable.
615          </para>
616         
617          <itemizedlist>
618            <listitem>
619              <para>
620                Increase the amount of memory that Tomcat is allowed to use. The default setting is
621                usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>.
622              </para>
623            </listitem>
624            <listitem>
625              <para>
626                Disable strict parsing of JSP files.
627                <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code>
628              </para>
629            </listitem>
630            <listitem>
631              <para>
632                Unless you have manually downloaded and installed JAI (Java Advanced
633                Imaging) native acceleration libraries (see <ulink 
634                url="http://java.sun.com/javase/technologies/desktop/media/jai/" />)
635                it is a good idea to disable the native acceleration of JAI.
636                <code>-Dcom.sun.media.jai.disableMediaLib=true</code>
637              </para>
638            </listitem>
639            <listitem>
640              <para>
641                Enable headless mode if your are setting up a server which doesn't have
642                a display device connected to it. <code>-Djava.awt.headless=true</code>.
643              </para>
644            </listitem>
645          </itemizedlist>
646         
647          <para>
648            Depending on your system there are probably several ways to set the
649            the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following
650            line (as a single line) close to the top of the <filename>catalina.sh</filename> 
651            script that comes with Tomcat (directory <filename
652            class="directory">bin</filename>):
653<programlisting>CATALINA_OPTS="-Xmx1G
654-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
655-Dcom.sun.media.jai.disableMediaLib=true
656-Djava.awt.headless=true"</programlisting>
657          </para>
658          <para>
659            For more information about Tomcat options see
660            <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/index.html" />.
661          </para>
662        </listitem>
663      </varlistentry>
664
665      <varlistentry>
666        <term>BASE and Tomcat</term>
667        <listitem>
668          <para>
669            Do the following:
670            <itemizedlist>
671              <listitem>
672                <para>
673                  Either move the <filename
674                  class="directory">&lt;base-dir&gt;/www</filename>
675                  directory to the Tomcat <filename
676                  class="directory">webapps</filename> directory or
677                  create a symbolic link from the Tomcat <filename
678                  class="directory">webapps</filename> directory to
679                  the <filename
680                  class="directory">&lt;base-dir&gt;/www</filename>
681                  directory
682<programlisting>cd /path/to/tomcat/webapps
683ln -s /path_to_base/www base2</programlisting>
684                </para>
685              </listitem>
686              <listitem>
687                <para>
688                  Make sure that user Tomcat is running as can read
689                  all objects in the directory defined by
690                  <emphasis>plugins.dir</emphasis> in file
691                  <filename>base.config</filename>.
692                </para>
693              </listitem>
694              <listitem>
695                <para>
696                  Make sure that user Tomcat is running as owns (i.e.,
697                  can read, write, delete and create) all objects in
698                  the directory, as well as the directory itself,
699                  defined by <emphasis>userfiles</emphasis> in file
700                  <filename>base.config</filename>.
701                </para>
702              </listitem>
703              <listitem>
704                <para>
705                  If you plan to install extensions you should make
706                  sure that the <filename
707                  class="directory">&lt;base-dir&gt;/www/extensions</filename>
708                  directory is writable by the user account Tomcat is
709                  running as.
710                </para>
711              </listitem>
712            </itemizedlist>
713          </para>
714          <para>
715            and finalise with start, or restart, Tomcat, and try
716            http://hostname:8080/base2 (change
717            <emphasis>hostname</emphasis> to your hostname and
718            <emphasis>base2</emphasis> if you selected another name
719            for the BASE Tomcat application) in your favourite
720            browser. The BASE log-in page should appear after a few
721            seconds.
722          </para>
723        </listitem>
724      </varlistentry>
725
726      <varlistentry>
727        <term>BASE, Apache, and Apache/Tomcat connector</term>
728        <listitem>
729          <para>
730            <emphasis>This step is optional</emphasis>.
731          </para>
732          <para>
733            If you want run the Tomcat server through the Apache web
734            server, you need to install the Apache version 2 web
735            server, available
736            from <ulink url="http://httpd.apache.org/" />,
737            and a apache-tomcat connector, available
738            from <ulink
739            url="http://tomcat.apache.org/connectors-doc/index.html" />
740          </para>
741        </listitem>
742      </varlistentry>
743
744      <varlistentry>
745        <term>Setup done!</term>
746        <listitem>
747          <para>
748            Happy BASEing. Now you can log on to your BASE server as
749            user <emphasis>root</emphasis> (use
750            the <emphasis>base_root_password</emphasis> from the
751            database initialisation step above). You should begin with
752            creating a couple user accounts, for more information on
753            how to create user accounts please refer to
754            <xref linkend="accounts"/>.
755          </para>
756        </listitem>
757      </varlistentry>
758
759    </variablelist>
760
761  </sect1>      <!-- Installation instructions -->
762
763  <sect1 id="installation.jobagents">
764    <title>Installing job agents</title>
765
766    <para>
767      It is important to understand that the BASE application can be
768      spread on to several computers. The main BASE application is
769      serving HTTP requests, the underlying database engine is
770      providing storage and persistence of data, and job agents can be
771      installed on computers that will serve the BASE installation
772      with computing power and perform analysis and run plug-ins. In a
773      straight forward setup one computer provides all services needed
774      for running BASE. From this starting point it is easy to add
775      computers to shares load from the BASE server by installing job
776      agents on these additional computers.
777    </para>
778
779    <para>
780      A job agent is a program running on a computer regularly
781      checking the BASE job queue for jobs awaiting execution. When
782      the job agent finds a job that it is enabled to execute, it
783      loads the plug-in and executes it. Job agents will in this way
784      free up resources on the BASE application server, and thus allow
785      the BASE server to concentrate on serving web pages. Job agents
786      are optional and must be installed and setup
787      separately. However, BASE is prepared for job agent setup and to
788      utilise the agents, but the agent are not required.
789    </para>
790
791    <para>
792      A job agent supports many configuration options that are not
793      supported by the internal job queue. For example, you can
794      <itemizedlist>
795        <listitem>
796          <para>
797            Specify exactly which plug-ins each job agent should be
798            able to execute.
799          </para>
800        </listitem>
801        <listitem>
802          <para>
803            Give some plug-ins higher priority than other plug-ins.
804          </para>
805        </listitem>
806        <listitem>
807          <para>
808            Specify which users/groups/projects should be able to use
809            a specific job agent.
810          </para>
811        </listitem>
812        <listitem>
813          <para>
814            Override memory settings and more for each plug-in.
815          </para>
816        </listitem>
817        <listitem>
818          <para>
819            Execute plug-ins in separate processes. Thus, a misbehaving
820            plug-in cannot bring the main application server down.
821          </para>
822        </listitem>
823        <listitem>
824          <para>
825            Add more computers with job agents as needed.
826          </para>
827        </listitem>
828      </itemizedlist>
829      All these options make it possible to create a very flexible
830      setup. For example one job agent can be assigned for importing
831      data only, another job agent can be assigned for running
832      analysis plug-ins for specific project only, and a third may be a
833      catch-all job agent that performs all low-priority jobs.
834    </para>
835
836    <sect2 id="installation.jobagents.serverside">
837      <title>BASE application server side setup</title>
838      <para>
839        <variablelist>
840          <varlistentry>
841            <term>Make sure the internal job queue doesn't execute all plug-ins</term>
842            <listitem>
843              <para>
844                The setting <command>jobqueue.internal.runallplugins</command>
845                should be set to <command>false</command> for the
846                BASE server. This setting is found in
847                the <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
848                file. The changes will not take effect until the
849                application server is restarted.
850              </para>
851
852            </listitem>
853          </varlistentry>
854          <varlistentry id="installation.jobagent.user_account">
855            <term>Enable the job agent user account</term>
856            <listitem>
857              <para>
858                During installation of BASE a user account is created
859                for the job agent. This account is used by the job
860                agents to log on to BASE. The account is disabled by
861                default and must be enabled. Enable the account and
862                set a password using the BASE web interface.
863                The same password must also be set in the
864                <filename>jobagent.properties</filename> file, see
865                item
866                <xref linkend="installation.jobagent.client.properties"/>
867                below.
868              </para>
869            </listitem>
870          </varlistentry>
871        </variablelist>
872      </para>
873    </sect2>
874
875    <sect2 id="installation.jobagents.database">
876      <title>Database server setup</title>
877      <para>
878        <variablelist>
879          <varlistentry id="installation.jobagent.database">
880            <term>Create a user account on the database</term>
881            <listitem>
882              <para>
883                This is the similar to granting database access for
884                the BASE server user in the in the regular BASE
885                installation, cf.
886                <xref
887                linkend="installation.main.database"/>.
888                You must create an account in the database that is
889                allowed to connect from the job agent server. MySQL
890                example:
891<programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password';
892GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting>
893
894                Replace <command>job.agent.host</command> with the
895                host name of the server that is going to run the job
896                agent. You should also set password. This password is
897                used in item
898                <xref linkend="installation.jobagent.client.config"/>
899                below in job agent server setup. You can use the same
900                database user and password as in the regular database
901                setup.
902              </para>
903            </listitem>
904          </varlistentry>
905        </variablelist>
906      </para>
907    </sect2>
908
909    <sect2 id="installation.jobagents.client">
910      <title>Job agent client setup</title>
911      <para>
912        <variablelist>
913          <varlistentry>
914            <term>Download and unpack a regular BASE distribution</term>
915            <listitem>
916              <para>
917                You <emphasis>must</emphasis> use the same version on
918                the web server and all job agents. You find the
919                downloads at
920                <ulink
921                url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink>
922              </para>
923            </listitem>
924          </varlistentry>
925          <varlistentry id="installation.jobagent.client.config">
926            <term>Edit the <filename>base.config</filename> file</term>
927            <listitem>
928              <para>
929                The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
930                file must be configured as in regular BASE
931                installation, cf.
932                <xref
933                linkend="installation.main.configuration"/>,
934                to use the same database as the web server
935                application. The most important settings are
936                <itemizedlist>
937                  <listitem>
938                    <para>
939                      <command>db.username</command>: The database
940                      user you created in item
941                      <xref
942                      linkend="installation.jobagent.database"/>
943                      above.
944                    </para>
945                  </listitem>
946                  <listitem>
947                    <para>
948                      <command>db.password</command>: The password for
949                      the user.
950                    </para>
951                  </listitem>
952                  <listitem>
953                    <para>
954                      <command>db.url</command>: The connection url to
955                      the database.
956                    </para>
957                  </listitem>
958                  <listitem>
959                    <para>
960                      <command>userfiles</command>: The path to the
961                      directory where user files are located. This
962                      directory must be accessible from all job
963                      agents, i.e., by nfs or other file system
964                      sharing method.
965                    </para>
966                  </listitem>
967                  <listitem>
968                    <para>
969                      <command>plugins.dir</command>: The path to the
970                      directory where plug-ins are located. This
971                      directory must be accessible from all job
972                      agents, i.e., by nfs or other file system
973                      sharing method.
974                    </para>
975                  </listitem>
976                </itemizedlist>
977                See the <xref linkend="appendix.base.config"/> for
978                more information about the settings in
979                the <filename>base.config</filename> file.
980              </para>
981            </listitem>
982          </varlistentry>
983          <varlistentry id="installation.jobagent.client.properties">
984            <term>Edit
985            the <filename>jobagent.properties</filename> file</term>
986            <listitem>
987              <para>
988                The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/jobagent.properties</filename>
989                file contains settings for the job agent. The most
990                important ones to specify value for are
991                <itemizedlist>
992                  <listitem>
993                    <para>
994                      <command>agent.password</command>: The password
995                      you set for the job agent user account in item
996                      <xref
997                      linkend="installation.jobagent.user_account"/>
998                      above.
999                    </para>
1000                  </listitem>
1001                  <listitem>
1002                    <para>
1003                      <command>agent.id</command>: An ID that must be
1004                      unique for each job agent accessing the BASE application.
1005                    </para>
1006                  </listitem>
1007                  <listitem>
1008                    <para>
1009                      <command>agent.remotecontrol</command>: The
1010                      name or ip address of the web server if you want it
1011                      to be able to display info about running
1012                      jobs. The job agent will only allow connections
1013                      from computers specified in this setting.
1014                    </para>
1015                  </listitem>
1016                </itemizedlist>
1017              </para>
1018              <para>
1019                The <filename>jobagent.properties</filename> file
1020                contains many more configuration options. See
1021                the <xref linkend="appendix.jobagent.properties"/> for
1022                more information.
1023              </para>
1024            </listitem>
1025          </varlistentry>
1026          <varlistentry>
1027            <term>Register the job agent</term>
1028            <listitem>
1029              <para>
1030                From the <filename>bin</filename> directory, register
1031                the job agent with
1032                <programlisting>./jobagent.sh register</programlisting>
1033              </para>
1034            </listitem>
1035          </varlistentry>
1036          <varlistentry>
1037            <term>Start the job agent</term>
1038            <listitem>
1039              <para>
1040                From the <filename>bin</filename> directory, start the
1041                job agent with
1042                <programlisting>./jobagent.sh start &amp;</programlisting>
1043              </para>
1044              <para>
1045                See the <xref linkend="appendix.jobagent.sh"/>
1046                for more information about what you can do
1047                with the job agent command line interface.
1048              </para>
1049            </listitem>
1050          </varlistentry>
1051        </variablelist>
1052      </para>
1053    </sect2>
1054
1055
1056    <sect2 id="installation.jobagents.configuration">
1057      <title>Configuring the job agent</title>
1058   
1059      <para>
1060        A job agent will not execute a plug-in unless the administrator
1061        has configured the job agent to do so. There are two things that
1062        must be done:
1063      </para>
1064     
1065      <itemizedlist>
1066        <listitem>
1067        <para>
1068          Share the job agent to the users, groups and project that should be
1069          able to use it. If the job agent is not shared, only the owner of
1070          job agent is allowed to use it. Use the regular <guilabel>Share</guilabel>
1071          functionality to specify which users/groups/projects
1072          should be able to use the job agent. You must give
1073          them at least <command>USE</command> permission.
1074          To give all users permission to the job agent share it
1075          to the <command>EVERYONE</command> group.
1076        </para>
1077        </listitem>
1078       
1079        <listitem>
1080        <para>
1081          Selecting plug-ins that the job agent should handle. This can be
1082          done either from the plug-in pages or from the job agent pages. To register
1083          a plug-in with one or more job agents from the plug-in pages, go
1084          to the edit view of the plug-in and select the <guilabel>Job
1085          agents</guilabel> tab. To do the same from the job agent pages,
1086          go to the edit view of the job agent and select
1087          the <guilabel>Plugins</guilabel> tab. The registration dialogues
1088          are very similar but only the plug-in side of registration is
1089          described here. The major difference is that it is not possible
1090          to enable/disable the internal job queue for plug-in when using
1091          the jobagent side of the registration.
1092        </para>
1093        </listitem>
1094      </itemizedlist>
1095   
1096      <figure id="plugins.figures.jobagents">
1097        <title>Select job agents for a plug-in</title>
1098        <screenshot>
1099          <mediaobject>
1100            <imageobject><imagedata 
1101              scalefit="1" width="100%"
1102              fileref="figures/plugin_jobagents.png" format="PNG"
1103              /></imageobject>
1104          </mediaobject>
1105        </screenshot>
1106      </figure>
1107   
1108      <helptext external_id="plugindefinition.jobagents" 
1109        title="Job agents">
1110       
1111        <para>
1112          Use this tab to specify which job agents the plug-in is
1113          installed and allowed to be executed on.
1114        </para>
1115       
1116        <variablelist>
1117        <varlistentry>
1118          <term><guilabel>Run this plugin on</guilabel></term>
1119          <listitem>
1120            <para>
1121              You may select if the internal job queue should execute the
1122              plug-in or not.
1123            </para>
1124          </listitem>
1125        </varlistentry>
1126        <varlistentry>
1127          <term><guilabel>Job agents</guilabel></term>
1128          <listitem>
1129            <para>
1130              A list with the job agents where the plug-in is installed and
1131              allowed to be executed. Select a job agent in this list to display
1132              more configuration options for the plug-in.
1133            </para>
1134          </listitem>
1135        </varlistentry>
1136        <varlistentry>
1137          <term><guilabel>Add job agents</guilabel></term>
1138          <listitem>
1139            <para>
1140              Use this button to open a pop-up window for selecting
1141              job agents.
1142            </para>
1143          </listitem>
1144        </varlistentry>
1145        <varlistentry>
1146          <term><guilabel>Remove</guilabel></term>
1147          <listitem>
1148            <para>
1149              Remove the selected plug-in from the list.
1150            </para>
1151          </listitem>
1152        </varlistentry>
1153        </variablelist>
1154       
1155        <para>
1156          The following properties are only displayed when a
1157          job agent has been selected in the list. Each job agent may have it's
1158          own settings of these properties. If you leave the values unspecified
1159          the job agent will use the default values specified on the
1160          <guilabel>Plugin</guilabel> tab.
1161        </para>
1162       
1163        <variablelist>
1164        <varlistentry>
1165          <term><guilabel>Max memory</guilabel></term>
1166          <listitem>
1167            <para>
1168              The maximum amount of memory the plug-in is allowed to use.
1169              Add around 40MB for the Java run-time environment and BASE.
1170              If not specified Java will choose it's default value which is 64MB.
1171            </para>
1172          </listitem>
1173        </varlistentry>
1174        <varlistentry>
1175          <term><guilabel>Trusted</guilabel></term>
1176          <listitem>
1177            <para>
1178              If the plug-in should be executed in a protected or
1179              unprotected environment. Currently, BASE only supports
1180              running plug-ins in an unprotected environment.
1181            </para>
1182          </listitem>
1183        </varlistentry>
1184        <varlistentry>
1185          <term><guilabel>Priority boost</guilabel></term>
1186          <listitem>
1187            <para>
1188              Used to give a plug-in higher priority in the job queue.
1189              Values between 0 and 10 are allowed. A higher value will
1190              give the plug-in higher priority. The priority boost is useful
1191              if we, for example, want to use one server mainly for importing
1192              data. By giving all import plugins a priority boost they will
1193              be executed before all other jobs, which will have to wait
1194              until there are no more waiting imports.
1195            </para>
1196          </listitem>
1197        </varlistentry>
1198        </variablelist>
1199       
1200        <seeother>
1201          <other external_id="plugindefinition.edit">Plug-in properties</other>
1202          <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other>
1203        </seeother>
1204      </helptext>
1205    </sect2>
1206
1207  </sect1>      <!-- job agent setup -->
1208
1209  <sect1 id="installation.serverconfigurations">
1210    <title>Server configurations</title>
1211    <para>
1212      Some server configurations can be done when the installation process is finished and
1213      BASE is up and running. Log into BASE with administration rights and then
1214      open the configuration dialog from menu
1215      <menuchoice>
1216        <guimenu>Administrate</guimenu>
1217        <guimenuitem>Server settings</guimenuitem>
1218      </menuchoice>.
1219      Each tab in the configuration dialog-window is described below.
1220    </para>
1221   
1222      <figure id="installation.figures.serverconfiguration">
1223        <title>Server configuration</title>
1224        <screenshot>
1225          <mediaobject>
1226            <imageobject><imagedata 
1227              fileref="figures/server_configuration.png" format="PNG"
1228              /></imageobject>
1229          </mediaobject>
1230        </screenshot>
1231      </figure>
1232     
1233    <variablelist>
1234      <varlistentry>
1235        <term>
1236          <guilabel>File transfer</guilabel>
1237        </term>
1238        <listitem>
1239          <helptext external_id="serverconfig.filetransfer" title="File transfer rate">
1240            <variablelist>
1241              <varlistentry>
1242                <term><guilabel>Max upload rate</guilabel></term>
1243                <listitem>
1244                  <para>
1245                    This is a limit of how many bytes of data that should be
1246                    transferred per second when uploading files to BASE. Prefixes
1247                    like k, M or G can be used for larger values, just like
1248                    described in the tab. The limit is per ongoing upload
1249                    and the default value is 100MB/s.
1250                  </para>
1251                </listitem>
1252              </varlistentry>
1253              <varlistentry>
1254                <term><guilabel>Max download rate</guilabel></term>
1255                <listitem>
1256                  <para>
1257                    This is a limit of how many bytes of data that should be
1258                    transferred per second when downloading files from BASE. Prefixes
1259                    like k, M or G can be used for larger values. The limit is per ongoing
1260                    download and the default value is unlimited.
1261                  </para>
1262                </listitem>
1263              </varlistentry>
1264              <varlistentry>
1265                <term><guilabel>Unlimited</guilabel></term>
1266                <listitem>
1267                  <para>
1268                    Check one or both to not limit the upload/download transfer rate.
1269                    In this case, the Internet connection of the server is the limit.
1270                  </para>
1271                </listitem>
1272              </varlistentry>
1273            </variablelist>
1274          </helptext>
1275        </listitem>
1276      </varlistentry>
1277      <varlistentry>
1278        <term>
1279          <guilabel>About</guilabel>
1280        </term>
1281        <listitem>
1282          <helptext external_id="serverconfig.about"
1283            title="Information about the server">
1284            <variablelist>
1285              <varlistentry>
1286                <term><guilabel>Administrator name</guilabel></term>
1287                <listitem>
1288                  <para>
1289                    Name of the responsible administrator. The name is displayed
1290                    at the bottom of each page in BASE and in the about-dialog.
1291                  </para>
1292                </listitem>
1293              </varlistentry>
1294              <varlistentry>
1295                <term><guilabel>Administrator email</guilabel></term>
1296                <listitem>
1297                  <para>
1298                    An email which the administrator can be contacted on. The
1299                    administrator name, visible at the bottom of each page, will
1300                    be linked to this email address.
1301                  </para>
1302                </listitem>
1303              </varlistentry>
1304              <varlistentry>
1305                <term><guilabel>About</guilabel></term>
1306                <listitem>
1307                  <para>
1308                    Text written in this field is displayed in the
1309                    <guilabel>About this server</guilabel> section on the login
1310                    page and in the about-dialog window. We recommend changing the
1311                    default Latin text to something meaningful, or remove it
1312                    to hide the section completely.
1313                  </para>
1314                </listitem>
1315              </varlistentry>
1316            </variablelist>
1317          </helptext>
1318        </listitem>
1319      </varlistentry>
1320      <varlistentry>
1321        <term>
1322          <guilabel>Get account</guilabel>
1323        </term>
1324        <listitem>
1325          <helptext external_id="serverconfig.getaccount"
1326            title="Instructions to get an account">
1327            <para>
1328              A description what a user should do to get
1329              an account on the particular BASE server. This text is linked
1330              to the <guilabel>Get an account!</guilabel> link on the login
1331              page. We recommend that the Latin text is replaced with some useful
1332              information, or that it is removed to hide the link.
1333            </para>
1334          </helptext>
1335        </listitem>
1336      </varlistentry>
1337      <varlistentry>
1338        <term>
1339          <guilabel>Forgotten password</guilabel>
1340        </term>
1341        <listitem>
1342          <helptext external_id="serverconfig.password"
1343            title="Instructions when password is forgotten.">
1344            <para>
1345              A description what a user should do if the password is forgotten.
1346              This text is linked
1347              to the <guilabel>Forgot your password?</guilabel> link on the login
1348              page. We recommend that the Latin text is replaced with some useful
1349              information, or that it is removed to hide the link.
1350            </para>
1351          </helptext>
1352        </listitem>
1353      </varlistentry>
1354      <varlistentry>
1355        <term>
1356          <guilabel>Links</guilabel>
1357        </term>
1358        <listitem>
1359          <helptext external_id="serverconfig.links" title="Configurable links">
1360            <para>
1361              External configurable link-types inside BASE.
1362              <note>
1363                <para>
1364                  Only link-types that have been set will be visible in the web
1365                  client.
1366                </para>
1367              </note>
1368            </para>
1369            <variablelist>
1370              <varlistentry>
1371                <term><guilabel>Help</guilabel></term>
1372                <listitem>
1373                  <para>
1374                    Links to where the help text is located. By default
1375                    this is set to the documentation for the latest released
1376                    BASE version on the BASE web site,
1377                    <ulink
1378                      url="http://base.thep.lu.se/chrome/site/doc/html/index.html">
1379                      http://base.thep.lu.se/chrome/site/doc/html/index.html</ulink>.
1380                   
1381                    If you want the documentation for a specific version you will
1382                    have to setup a site for that yourself and then change the link
1383                    to that site. The documentation is included in the downloaded package
1384                    in the directory <filename>&lt;basedir&gt;/doc/html</filename>.
1385                  </para>
1386                </listitem>
1387              </varlistentry>
1388              <varlistentry>
1389                <term>
1390                  <guilabel>FAQ</guilabel>
1391                </term>
1392                <listitem>
1393                  <para>Where frequently asked questions can be found. Empty by default.</para>
1394                </listitem>
1395              </varlistentry>
1396              <varlistentry>
1397                <term>
1398                  <guilabel>Report a bug</guilabel>
1399                </term>
1400                <listitem>
1401                  <para>
1402                    Where the user could report bugs, feature request or
1403                    perhaps other feedback that concerns the program. As default
1404                    this is set to the feedback section on BASE web site,
1405                    <ulink url="http://base.thep.lu.se/#Feedback">http://base.thep.lu.se/#Feedback</ulink>.
1406                    Note that users must login in order to submit information.
1407                  </para>
1408                </listitem>
1409              </varlistentry>
1410            </variablelist>
1411          </helptext>
1412        </listitem>
1413      </varlistentry>
1414    </variablelist>
1415   
1416    <sect2 id="installation.broadcast">
1417      <title>Sending a broadcast message to logged in users</title>
1418
1419      <para>
1420        It is possible to send a message to all logged in user.
1421        Open the
1422        <menuchoice>
1423          <guimenu>Administrate</guimenu>
1424          <guimenuitem>Broadcast message</guimenuitem>
1425        </menuchoice> dialog box.
1426      </para>
1427     
1428      <figure id="installation.figures.broadcast">
1429        <title>Broadcast message</title>
1430        <screenshot>
1431          <mediaobject>
1432            <imageobject><imagedata 
1433              fileref="figures/broadcast_message.png" format="PNG"
1434              /></imageobject>
1435          </mediaobject>
1436        </screenshot>
1437      </figure>
1438     
1439      <helptext external_id="broadcast.message" title="Broadcast message">
1440        <para>
1441        This dialog allows you to specify a message that is sent to all
1442        logged in users as well as on the login form. It is also possible
1443        to "disable" login.
1444        </para>
1445        <variablelist>
1446        <varlistentry>
1447          <term><guilabel>Title</guilabel></term>
1448          <listitem>
1449            <para>
1450            The title of the message. It should be a short and concise to
1451            avoid confusion. The title will be displayed on a lot of places
1452            and a user may have to click on it to read the more detailed
1453            message.
1454            </para>
1455          </listitem>
1456        </varlistentry>
1457        <varlistentry>
1458          <term><guilabel>Disable login</guilabel></term>
1459          <listitem>
1460            <para>
1461            Mark this check-box to try to prevent new users from logging in. To
1462            avoid problems that can be caused by blocking the server admin out,
1463            the login is not completely disabled. Any user can still login but
1464            only after by-passing several warnings.
1465            </para>
1466          </listitem>
1467        </varlistentry>
1468        <varlistentry>
1469          <term><guilabel>Message</guilabel></term>
1470          <listitem>
1471            <para>
1472            If needed, a longer message giving more information. Users may
1473            have to click on a link to be able to see the complete message.
1474            </para>
1475          </listitem>
1476        </varlistentry>
1477        </variablelist>
1478       
1479        <note>
1480          The message will be enabled until it is manually removed by saving
1481          an empty form, or until the Tomcat server is restarted. Since the
1482          message is only kept in memory, a restart will always remove it.
1483        </note>
1484     
1485      </helptext>
1486     
1487    </sect2>
1488   
1489  </sect1>
1490
1491  <sect1 id="installation.migrate">
1492    <title>Migrating from MySQL to PostgreSQL</title>
1493   
1494    <para>
1495      It is possible to migrate a BASE installation on a MySQL database to a
1496      PostgreSQL database. In a real-world scenario a migration is probably coupled
1497      with a hardware upgrade, i.e. the MySQL installation is on one (the old) server
1498      and the PostgreSQL installation is on another (the new) server. While
1499      this is not any problem per se, it requires a few extra steps to ensure that
1500      everything has been moved to the new server. There are three main steps involved:
1501    </para>
1502   
1503    <variablelist>
1504      <varlistentry>
1505        <term>Export</term>
1506        <listitem>
1507          <para>
1508          The first step is to export all data in the existing database. Use
1509          the following procedure:
1510          </para>
1511         
1512          <orderedlist>
1513            <listitem>
1514              <para>
1515              Upgrade to the latest BASE release. This is recommended since
1516              it probably has fewer bugs.
1517              </para>
1518            </listitem>
1519
1520            <listitem>
1521              <para>
1522              Make sure that no other processes are writing to the database
1523              when the export is running. Shut down Tomcat and all job agents.
1524              It may also be a good idea to ensure that no backup scripts or
1525              other external programs are reading from the database at the same
1526              time. If the database is large, this may affect performance due to
1527              increased disk I/O.
1528              </para>
1529            </listitem>
1530           
1531            <listitem>
1532              <para>
1533              Create a temporary working directory in a suitable
1534              location. This directory will be used for storing the
1535              exported data. Disk I/O performance may be better if
1536              this directory is on a different disk than what the
1537              database is using. Ensure that the location has enough
1538              free space to hold all data from the BASE database. The dump
1539              typically uses less than 10% of the disk space used by the
1540              MySQL tables.
1541              </para>
1542            </listitem>
1543
1544            <listitem>
1545              <para>
1546              Make sure that you have configured migration-specific settings
1547              in the <filename>base.config</filename> file. In most cases the
1548              default settings should be good, but if you are experiencing
1549              performance problems it may be necessary to change some settings.
1550              See <xref linkend="appendix.base.config.migrate" /> for more
1551              information.
1552              </para>
1553            </listitem>
1554
1555            <listitem>           
1556              <para>
1557                Start the export by changing to the <filename
1558                class="directory">&lt;base-dir&gt;/bin/</filename>
1559                directory and execute:
1560              </para>
1561<programlisting>
1562./migrate.sh export <replaceable>/path/to/migration/dir</replaceable>
1563</programlisting>
1564              <para>
1565                where <replaceable>/path/to/migration/dir</replaceable>
1566                is replaced with the path to the working directory created above.
1567                Depending on the size of the BASE installation the export may
1568                take a long time.
1569              </para>
1570            </listitem>
1571          </orderedlist>
1572         
1573          <note>
1574            <para>
1575              Make sure that the migration working directory is empty to perform
1576              a full export. Existing files in the directory causes the corresponding
1577              tables to be skipped. This can be useful when debugging and after a
1578              server crash, since the export will resume where it stopped. Just make
1579              sure that the database hasn't been modified in the meantime.
1580            </para>
1581          </note>
1582          <warning>
1583            <para>
1584            When exporting, make sure that no other process is updating the
1585            database since that may create an inconsistent snapshot. The
1586            export process does not lock the database or take any other means
1587            to protect it against concurrent modifications.
1588            </para>
1589          </warning>
1590        </listitem>
1591      </varlistentry>
1592     
1593      <varlistentry>
1594        <term>Moving data</term>
1595        <listitem>
1596          <para>
1597          This step is about moving the data from the old BASE server to the
1598          new BASE server. If the migration is taking place on a single server,
1599          this step can probably be skipped.
1600          </para>
1601         
1602          <orderedlist>
1603            <listitem>
1604              <para>
1605              Download and unpack the BASE software on the new server. Make sure that you are
1606              using the same version as on the old server. It is also important that
1607              the database is identically configured. Pay special attention
1608              to the <filename>extended-properties.xml</filename> and
1609              <filename>raw-data-types.xml</filename> files and any files
1610              in the <filename
1611              class="directory">&lt;base-dir&gt;/WEB-INF/classes/extended-properties</filename>
1612              and <filename
1613              class="directory">&lt;base-dir&gt;/WEB-INF/classes/raw-data-types</filename>
1614              directories.
1615              The import program protects against some mistakes by comparing
1616              the column names from the export with the column names in the new
1617              database, but it will, for example, not check that data types match.
1618              </para>
1619             
1620              <tip>
1621                The easiest way to do this is to simply copy the BASE installation
1622                from the old server to the new server. Then, go through the
1623                configuration files and make sure that paths are correct.
1624              </tip>
1625             
1626            </listitem>
1627         
1628            <listitem>
1629              <para>
1630              Move user files from the old server to the new server. Make sure that
1631              the <property>userfiles</property> setting in <filename>base.config</filename>
1632              is correct.
1633              </para>
1634            </listitem>
1635           
1636            <listitem>
1637              <para>
1638              Move plug-ins from the old server to the new server. Make sure that
1639              the <property>plugins.dir</property> setting in <filename>base.config</filename>
1640              is correct.
1641              </para>
1642            </listitem>
1643
1644            <listitem>
1645              <para>
1646              Check other settings in <filename>base.config</filename> and
1647              other configuration files for settings that may be affected by
1648              the move.
1649              </para>
1650            </listitem>
1651         
1652          </orderedlist>
1653         
1654        </listitem>
1655      </varlistentry>
1656     
1657      <varlistentry>
1658        <term>Import</term>
1659        <listitem>
1660          <para>
1661            When everything has been moved and is properly configured it is
1662            time to start with the import.
1663          </para>
1664         
1665          <orderedlist>
1666            <listitem>
1667              <para>
1668              Create a new empty database following the
1669              instructions in <xref linkend="installation.main.database" />.
1670              Make the corresponding changes in <filename>base.config</filename>
1671              so that the BASE installation points to the new database.
1672              Also, make sure that you have configured migration-specific settings
1673              in the <filename>base.config</filename> file. In most cases the
1674              default settings should be good, but if you are experiencing
1675              performance problems it may be necessary to change some settings.
1676              See <xref linkend="appendix.base.config.migrate" /> for more
1677              information.
1678              </para>
1679            </listitem>
1680         
1681            <listitem>
1682              <para>
1683              Read the
1684              <ulink url="http://www.postgresql.org/docs/9.1/interactive/populate.html">http://www.postgresql.org/docs/9.1/interactive/populate.html</ulink>
1685              document from the PostgreSQL documentation and consider implementing some
1686              of the tips. The migration script makes sure that no indexes or foreign
1687              key constraints are active during the data import, but the tips about memory,
1688              checkpoint intervals, WAL archiving, etc. (section 14.4.5 and on) can be useful.
1689              It may also be a good idea to turn off the auto-vacuum daemon during the import.
1690              </para>
1691            </listitem>
1692           
1693            <listitem>
1694              <para>
1695                Start the import by changing to the <filename
1696                class="directory">&lt;base-dir&gt;/bin/</filename>
1697                directory and execute:
1698              </para>
1699<programlisting>
1700./migrate.sh import <replaceable>/path/to/migration/dir</replaceable>
1701</programlisting>
1702              <para>
1703                where <replaceable>/path/to/migration/dir</replaceable>
1704                is replaced with the path to the directory where
1705                the exported data is stored. Depending on
1706                the size of the BASE installation this may take a long time.
1707              </para>
1708             
1709              <para>
1710                When the import has been completed, run this command
1711                to create the last missing indexes:
1712              </para>
1713<programlisting>
1714./updateindexes.sh
1715</programlisting>
1716             
1717              <note>
1718                <title>Installations with separate web and database servers</title>
1719                <para>
1720                Both export and import may be executed against remote MySQL/PostgreSQL
1721                servers without limitation. The migration working directory need only
1722                to be accessible by the BASE migration program.
1723                </para>
1724              </note>
1725             
1726            </listitem>
1727           
1728            <listitem>
1729              <para>
1730              Restart Tomcat and verify that the migration was successful. Eg.
1731              check that you can log in to BASE, that you can access files,
1732              that plug-ins are working, etc. Then, shut everything down again.
1733              </para>
1734            </listitem>
1735
1736            <listitem>
1737              <para>
1738              Setup backup procedures for the new server. Verify that the
1739              backup is working before starting up Tomcat again.         
1740              Restart any job agents (make sure that the are configured to use
1741              the new server). When everything is up and running again, the
1742              <replaceable>/path/to/migration/dir</replaceable> directory
1743              and all files can be deleted.
1744              </para>
1745            </listitem>
1746          </orderedlist>
1747       
1748        </listitem>
1749      </varlistentry>
1750    </variablelist>
1751   
1752  </sect1>
1753
1754</chapter>
Note: See TracBrowser for help on using the repository browser.