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

Last change on this file since 7545 was 7545, checked in by Nicklas Nordborg, 3 years ago

References #2131: Add support for installing multiple authentication managers

Added note to the update information about the changes.

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