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

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

References #2152: Test BASE with Tomcat 9

Updated documentation to recommend Tomcat 9 instead of Tomcat 8.

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