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

Last change on this file since 7161 was 7161, checked in by Nicklas Nordborg, 6 years ago

References #2011: Check that session id and client id match every time a new page is requested

Added notes in the documentation that this change may affect backwards compatibility.

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