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

Last change on this file since 5838 was 5838, checked in by Nicklas Nordborg, 11 years ago

Fixes #1635: Test BASE with Java 7

BASE itself seems to be working just fine. Compilation with Java 7 needs to set the 'javac.bootclasspath' to point to a JRE 6 installation. The recommended approach is to create build.properties and set the value in that file. Eg.

javac.bootclasspath /path/to/jdk-6/jre
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 52.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 5838 2011-11-01 11:10:57Z nicklas $
7
8  Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
9  Copyright (C) 2008 Jari Häkkinen, Nicklas Nordborg, Martin Svensson
10  Copyright (C) 2009 Jari Häkkinen, Nicklas Nordborg
11
12  This file is part of BASE - BioArray Software Environment.
13  Available at http://base.thep.lu.se/
14
15  BASE is free software; you can redistribute it and/or
16  modify it under the terms of the GNU General Public License
17  as published by the Free Software Foundation; either version 3
18  of the License, or (at your option) any later version.
19
20  BASE is distributed in the hope that it will be useful,
21  but WITHOUT ANY WARRANTY; without even the implied warranty of
22  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
23  GNU General Public License for more details.
24
25  You should have received a copy of the GNU General Public License
26  along with BASE. If not, see <http://www.gnu.org/licenses/>.
27-->
28
29<chapter id="installation">
30
31  <title>Installation and upgrade instructions</title>
32
33  <note>
34    <para>
35    These instructions apply only to the BASE release which this
36    document is a part of. The instructions here assume
37    that <ulink url="http://tomcat.apache.org/">Apache Tomcat 6</ulink> is used
38    on the server side. Other servlet engines may work but we only
39    test with Tomcat.
40    </para>
41  </note>
42
43  <sect1 id="installation.upgrade">
44    <title>Upgrade instructions</title>
45
46    <important id="installation.upgrade.important">
47      <title>Important information for upgrading from BASE 2.17 to BASE 3.0</title>
48     
49      <bridgehead>Upgrading is supported from BASE 2.17 only</bridgehead>
50      <para>
51        If your BASE is an older 2.x version you'll need to upgrade
52        to BASE 2.17 before an upgrade to BASE 3.0 is possible.
53      </para>
54
55      <warning>
56        <title>Make sure that you have a recent backup of the BASE 2.17 database</title>
57        <para>
58          Before starting the upgrade from BASE 2.17 to BASE 3 ensure that you
59          have a recent backup. If the upgrade fails you must restore the
60          2.17 database before you can try again. The upgrade only changes the
61          'static' part of the database, so you do not have to restore the
62          'dynamic' part or the uploaded files.
63        </para>
64      </warning>
65
66      <bridgehead>Old plug-ins and extensions may not work</bridgehead>
67      <para>
68        The BASE API has changed in several places and it is not certain that
69        plug-ins and extensions developed for BASE 2 works with BASE 3. The
70        upgrade will disable all plug-ins and extensions that are currently installed.
71        Before you upgrade we recommend that you go through all (external) plug-ins
72        and check if there is an updated version. The recommended approach
73        is to first upgrade BASE and then install updated versions of plug-ins
74        and extensions following the instructions in <xref 
75        linkend="plugins.installation"/>.
76      </para>
77     
78      <para>
79        If there is no updated version of a specific plug-in you may try
80        a manual re-installation of the old plug-ins. Follow the instructions
81        in <xref linkend="plugins.installation.manual" />.
82      </para>
83     
84      <para>
85        If there is no updated version and the old plug-in doesn't work with
86        BASE 3, you'll need to decide if you really need the plug-in or if
87        the upgrade should wait until a new version of the plug-in
88        has been released.
89      </para>
90     
91      <bridgehead>Batch item importer changes</bridgehead>
92      <para>
93        There are several changes to batch item importers that may affect
94        current workflows and file templates used for importing data.
95      </para>
96     
97      <itemizedlist>
98        <listitem>
99          <para>
100            Sample and extract importers: The 'pooled' column is no longer used.
101            Instead a 'parent type' column should be used with
102            the parent type as a string value (BIOSOURCE, SAMPLE or EXTRACT).
103            Existing importer configurations and file templates may have to be
104            updated. If no parent type is specified the sample importer assumes
105            a biosource and the extract importer assumes a sample.
106          </para>
107        </listitem>
108        <listitem>
109          <para>
110            Labeled extract importer: This has been deprecated and it is recommended
111            that the <emphasis>Extract importer</emphasis> is used instead.
112            We recommend that existing labeled extract importer configurations are re-created as extract
113            importer configurations. The old labeled extract importer can be
114            re-enabled, but note that the existing configurations still need
115            to be changed due to the 'pooled' column is no longer used.
116          </para>
117        </listitem>
118        <listitem>
119          <para>
120            Hybridization importer: This has been deprecated and we recommend
121            that the <emphasis>Physical bioassay importer</emphasis> is used instead.
122            Existing hybridization importer configurations should be re-created as
123            physical bioassay importer configurations.
124          </para>
125        </listitem>
126        <listitem>
127          <para>
128            Scan importer: This has been deprecated and it is recommended
129            that the <emphasis>Derived bioassay importer</emphasis> is used instead.
130            Existing scan importer configurations should be re-created as derived
131            bioassay importer configurations.
132          </para>
133        </listitem>
134      </itemizedlist>
135     
136      <note>
137        The deprecated importers can be re-enabled by an administrator from the
138        <menuchoice>
139          <guimenu>Administrate</guimenu>
140          <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
141          <guimenuitem>Overview</guimenuitem>
142        </menuchoice> page, but they are
143        lacking features that are available in the new importers so this is not
144        something that we recommend.
145      </note>
146     
147    </important>
148   
149    <para>
150      As always, backup your database before attempting an
151      upgrade. The BASE team performs extensive testing before
152      releasing a new version of BASE but there are always a
153      possibility for unexpected events during upgrades. In upgrades
154      requiring a change in the underlying database there is no
155      (supported) way to revert to a previous version of BASE using
156      BASE tools, you need to use your backup for this use case.
157    </para>
158
159    <para>
160      The strategy here is to install the new BASE release to another
161      directory than the one in use. This requires transfer of
162      configuration settings to the new install but more on that
163      below.
164    </para>
165
166    <variablelist>
167      <varlistentry>
168        <term>Shut down the Tomcat server</term>
169        <listitem>
170          <para>
171            If the BASE application is not shut down already, it is
172            time to do it now. Do something like <command>sudo
173            /etc/init.d/tomcat6.0 stop</command>
174          </para>
175         
176          <tip>
177            <title>Notify logged in users!</title>
178            <para>
179              If there are users logged in to your BASE server, it may
180              be nice of you to notify them a few minutes prior to shutting
181              down the BASE server. See <xref linkend="installation.broadcast" />.
182            </para>
183          </tip>
184        </listitem>
185      </varlistentry>
186
187      <varlistentry>
188        <term>Rename your current server</term>
189        <listitem>
190          <para>
191            Rename your current BASE installation <command>mv
192              /path/to/base /path/to/base_old</command>.
193          </para>
194        </listitem>
195      </varlistentry>
196
197      <varlistentry>
198        <term>Download and unpack BASE</term>
199        <listitem>
200          <para>
201            There are several ways to download BASE. Please refer to
202            section <xref linkend="resources.home_page.download"/> for
203            information on downloading BASE, and select the item
204            matching your download option:
205          </para>
206
207          <variablelist>
208            <varlistentry>
209              <term><emphasis>Pre-compiled package</emphasis></term>
210              <listitem>
211                <para>
212                  If you selected to download a pre-compiled package,
213                  unpack the downloaded file with <command>tar zxpf
214                  base-...tar.gz</command>.
215                </para>
216              </listitem>
217            </varlistentry>
218
219            <varlistentry>
220              <term><emphasis>Source package</emphasis></term>
221              <listitem>
222                <para>
223                  If you selected to download a source package, unpack
224                  the downloaded file with <command>tar zxpf
225                  base-...src.tar.gz</command>. Change to the new
226                  directory, and issue <command>ant
227                  package.bin</command>. This will create a binary
228                  package in the current directory. Unpack this new
229                  package (outside of the source file hierarchy).
230                </para>
231              </listitem>
232            </varlistentry>
233
234            <varlistentry>
235              <term><emphasis>Subversion checkout</emphasis></term>
236              <listitem>
237                <para>
238                  This option is for advanced users only and is not
239                  covered here. Please refer to
240                  <ulink url="http://base.thep.lu.se/wiki/BuildingBase" /> for information on
241                  this download option.
242                </para>
243              </listitem>
244            </varlistentry>
245
246          </variablelist>
247        </listitem>
248
249      </varlistentry>
250
251      <varlistentry>
252        <term>Transfer files and settings</term>
253        <listitem>
254          <para>
255            Settings from the previous installation must be
256            transferred to the new installation. This is most easily
257            done by comparing the configuration files from the
258            previous install with the new files. Do not just copy the
259            old files to the new install since new options may have
260            appeared.
261          </para>
262          <para>
263            In the main BASE configuration file,
264            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>,
265            fields that needs to be transferred are usually
266            <emphasis>db.username</emphasis>,
267            <emphasis>db.password</emphasis>,
268            and <emphasis>userfiles</emphasis>.
269          </para>
270          <para>
271            Local settings in the raw data
272            tables, <filename>&lt;base-dir&gt;/www/WEB-INF/classes/raw-data-types.xml</filename>,
273            may need to be transferred. This also includes all files in
274            the <filename>&lt;base-dir&gt;/www/WEB-INF/classes/raw-data-types</filename> and
275            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/extended-properties</filename>
276            directories.
277          </para>
278        </listitem>
279      </varlistentry>
280
281      <varlistentry>
282        <term>Updating database schema</term>
283        <listitem>
284          <para>
285            It is recommended that you also perform an update of your
286            database schema.  Running the update scripts are not
287            always necessary when upgrading BASE, but the running the
288            update scripts are safe even in cases when there is no
289            need to run them. Change directory
290            to <filename
291            class="directory">&lt;base-dir&gt;/bin/</filename> and issue
292<programlisting>
293sh ./updatedb.sh [base_root_login] <emphasis>base_root_password</emphasis>
294sh ./updateindexes.sh
295</programlisting>
296            where <emphasis>base_root_login</emphasis> is the login
297            for the root user and <emphasis>base_root_password</emphasis> is the
298            password. The login is optional. If not specified,
299            <constant>root</constant> is used as the login.
300          </para>
301        </listitem>
302      </varlistentry>
303
304      <varlistentry>
305        <term>Start Tomcat</term>
306        <listitem>
307          <para>
308            Start the Tomcat server: <command>sudo
309              /etc/init.d/tomcat6.0 start</command>
310          </para>
311        </listitem>
312      </varlistentry>
313
314    </variablelist>
315
316    <para>
317      Done! Upgrade of BASE is finished.
318    </para>
319
320  </sect1>      <!-- Upgrade instructions -->
321
322  <sect1 id="installation.main">
323    <title>Installation instructions</title>
324
325    <variablelist>
326
327      <varlistentry>
328        <term>Java</term>
329        <listitem>
330          <para>
331            Download and install Java SE 6, available from
332            <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html" />.
333            You can select either the JDK or the JRE version. We have only made a few tests
334            with BASE and Java SE 7. While it seems to be working just fine we can't make
335            any promises or provide any support for it.
336          </para>
337        </listitem>
338      </varlistentry>
339
340      <varlistentry>
341        <term>Tomcat</term>
342        <listitem>
343          <para>
344            Download and install Apache Tomcat 6.0.20 or any later 6.x release,
345            available from <ulink
346            url="http://tomcat.apache.org" />. We have not yet tested BASE
347            with Tomcat 7 so we can't tell if it works or not.
348            There are a few configuration options that are needed to
349            make Tomcat work properly with BASE. The options are set in the
350            <code>CATALINA_OPTS</code> environment variable.
351          </para>
352         
353          <itemizedlist>
354            <listitem>
355              <para>
356                Increase the amount of memory that Tomcat is allowed to use. The default setting is
357                usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>.
358              </para>
359            </listitem>
360            <listitem>
361              <para>
362                Disable strict parsing of JSP files.
363                <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code>
364              </para>
365            </listitem>
366            <listitem>
367              <para>
368                Unless you have manually downloaded and installed JAI (Java Advanced
369                Imaging) native acceleration libraries (see <ulink 
370                url="http://java.sun.com/javase/technologies/desktop/media/jai/" />)
371                it is a good idea to disable the native acceleration of JAI.
372                <code>-Dcom.sun.media.jai.disableMediaLib=true</code>
373              </para>
374            </listitem>
375            <listitem>
376              <para>
377                Enable headless mode if your are setting up a server which doesn't have
378                a display device connected to it. <code>-Djava.awt.headless=true</code>.
379              </para>
380            </listitem>
381         
382          </itemizedlist>
383         
384          <para>
385            Depending on your system there are probably several ways to set the
386            the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following
387            line (as a single line) close to the top of the <filename>catalina.sh</filename> 
388            script that comes with Tomcat (directory <filename
389            class="directory">bin</filename>):
390<programlisting>CATALINA_OPTS="-Xmx1G
391-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
392-Dcom.sun.media.jai.disableMediaLib=true
393-Djava.awt.headless=true"</programlisting>
394          </para>
395          <para>
396            For more information about Tomcat options see
397            <ulink url="http://tomcat.apache.org/tomcat-6.0-doc/index.html" />.
398          </para>
399        </listitem>
400      </varlistentry>
401
402      <varlistentry>
403        <term>Set up an SQL database</term>
404        <listitem>
405          <para>
406            BASE
407            utilize <ulink
408            url="http://www.hibernate.org/">Hibernate</ulink> for
409            object persistence to a relational database. Hibernate
410            supports many database engines, but so far we only work
411            with <ulink url="http://www.mysql.com">MySQL</ulink>
412            and <ulink
413            url="http://www.postgresql.org/">PostgreSQL</ulink>.
414          </para>
415
416          <variablelist>
417            <varlistentry>
418              <term>MySQL</term>
419              <listitem>
420                <para>
421                  Download and install MySQL (tested with version
422                  5.1), available from
423                  <ulink url="http://www.mysql.com/" />. You need to
424                  be able to connect to the server over TCP, so
425                  the <emphasis>skip-networking</emphasis> option
426                  must <command>not</command> be used. The InnoDB
427                  table engine is also needed, so do not disable them
428                  (not that you would) but you may want to tune the
429                  InnoDB behaviour before creating BASE
430                  databases. BASE comes pre-configured for MySQL so
431                  there is no need to change database settings in the
432                  BASE configuration files.
433                </para>
434              </listitem>
435            </varlistentry>
436            <varlistentry>
437              <term>PostgreSQL</term>
438              <listitem>
439                <para>
440                  PostgreSQL 8.4 seems to be working very well with
441                  BASE and Hibernate. Download and install PostgreSQL,
442                  available from
443                  <ulink url="http://www.postgresql.org/" />. you must
444                  edit
445                  your <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
446                  file. Uncomment the settings for PostgreSQL and
447                  comment out the settings for MySQL.
448                </para>
449               
450                <note>
451                  <para>
452                  PostgreSQL versions prior to 8.2 have a non-optimal solution
453                  for locking rows in certain situations. This may cause two
454                  seemingly independent transactions to lock if they just
455                  reference a common database row. This may happen, for example,
456                  when importing raw data that have references to the same
457                  reporters. The problem has been solved in PostgreSQL 8.2.
458                  </para>
459                </note>
460                <para>
461                  We have not yet tested BASE with PostgreSQL 9 so we can't tell
462                  if it works or not.
463                </para>
464              </listitem>
465            </varlistentry>
466          </variablelist>
467
468        </listitem>
469      </varlistentry>
470
471      <varlistentry>
472        <term>BASE (download and unpacking)</term>
473        <listitem>
474          <para>
475            <ulink
476            url="http://base.thep.lu.se/wiki/DownloadPage">Download
477            BASE</ulink> and unpack the downloaded file,
478            i.e. <command>tar zxpf base-...tar.gz</command>. If you
479            prefer to have the bleeding edge version of BASE, perform
480            a checkout of the source from the subversion repository
481            (subversion checkout instructions at
482            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
483            trac site</ulink>).
484          </para>
485          <para>
486            If you choose to download the binary package, skip to the
487            next item. The rest of us, read on and compile BASE. If
488            you downloaded a source distribution, unpack the
489            downloaded file <command>tar zxpf
490            base-...src.tar.gz</command>, or you may have performed a
491            subversion checkout.  Change to the 'root' base2
492            directory, and issue <command>ant
493            package.bin</command>. This will create a binary package
494            in the base2 'root' directory. Unpack this new package
495            (outside of the source file hierarchy), and from now on
496            the instructions are the same irrespective where you got
497            the binary package.
498          </para>
499          <para>
500            <emphasis>This section is intended for advanced users and
501              programmers only. In cases when you want to change the
502              BASE code and try out personalized features it may be
503              advantageous to run the tweaked BASE server against the
504              development tree. Instructions on how to accomplish this
505              is available in the
506              <ulink
507              url="http://base.thep.lu.se/wiki/BuildingBase">building
508              BASE document</ulink>. When you return back after
509              compiling in the subversion tree you can follow the
510              instruction here (with obvious changes to
511              paths).</emphasis>
512          </para>
513        </listitem>
514      </varlistentry>
515
516      <varlistentry id="installation.main.database">
517        <term>BASE (database engine)</term>
518        <listitem>
519          <para>
520            Instructions for MySQL and PostgreSQL are available
521            below. The database names (base2 and base2dynamic is used
522            here), the <emphasis>db_user</emphasis>, and
523            the <emphasis>db_password</emphasis> can be changed during
524            the creation of the databases. It is recommended to change
525            the <emphasis>db_password</emphasis>, the other changes
526            can be made if desired. The database names,
527            the <emphasis>db_user</emphasis>, and
528            the <emphasis>db_password</emphasis> are needed in a later
529            step below when configuring BASE.
530          </para>
531          <note>
532            Note that the <emphasis>db_user</emphasis> name
533            and <emphasis>db_password</emphasis> set here is used
534            internally by BASE in communication with the database and
535            is never used to log on to the BASE application.
536          </note>
537          <important>
538            <title>The database must use the UTF-8 character set</title>
539            <para>
540              Otherwise there will be a problem with storing values
541              that uses characters outside the normal Latin1 range, for
542              example unit-related such as µ (micro) and Ω (ohm).
543            </para>
544          </important>
545          <variablelist>
546            <varlistentry>
547              <term>MySQL</term>
548              <listitem>
549                <para>
550                  Create a new database for BASE, and add a
551                  <emphasis>db_user</emphasis> with at least
552                  <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
553                  <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
554                  <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
555                  <emphasis>INDEX</emphasis>,
556                  and <emphasis>ALTER</emphasis> permission for the
557                  new database. To do this, connect to your MySQL
558                  server and issue the next lines:
559<programlisting>CREATE DATABASE base2 DEFAULT CHARACTER SET utf8;
560CREATE DATABASE base2dynamic DEFAULT CHARACTER SET utf8;
561GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
562GRANT ALL ON base2dynamic.* TO db_user@localhost;</programlisting>
563                </para>             
564                <para>
565                  The <filename>&lt;base-dir&gt;/misc/sql/createdb.mysql.sql</filename>
566                  file contains the above statements and can be used
567                  by the <filename>mysql</filename> command-line tool
568                  (remember to edit
569                  the <emphasis>db_user</emphasis>,
570                  <emphasis>db_password</emphasis>,
571                  and the database names in the script file before
572                  executing the command): <command>mysql -uroot -p
573                  &lt; ./misc/sql/createdb.mysql.sql</command>. The
574                  header in the script file contains further
575                  information about the script.
576                </para>
577              </listitem>
578            </varlistentry>
579            <varlistentry>
580              <term>PostgreSQL</term>
581              <listitem>
582                <para>
583                  Create a new database for BASE, and add a
584                  <emphasis>db_user</emphasis> with the proper
585                  privileges. To do this, log in as your PostgreSQL
586                  user and issue these lines (omit comments):
587<programlisting>createuser db_user -P
588  # this will prompt for an password for the new user, and issue two
589  # more question that should be answered with character 'n' for no.
590createdb --owner db_user --encoding UTF8 base2
591psql base2
592  # this will start the psql command line tool. Issue the next line
593  # within the tool and quit with a '\q'.
594CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting>
595                  The <filename>&lt;base-dir&gt;/misc/sql/createdb.postgresql.sql</filename>
596                  file contains the above statements and can be used
597                  by the <filename>psql</filename> command-line tool:
598                  <command>psql -f ./misc/sql/createdb.posgres.sql
599                    template1</command> The header in the script file
600                  contains further information about the script.
601                </para>
602              </listitem>
603            </varlistentry>
604          </variablelist>
605        </listitem>
606      </varlistentry>
607
608      <varlistentry>
609        <term>BASE (file storage setup)</term>
610        <listitem>
611          <para>
612            An area for file storage must be setup. Create an empty
613            directory in a proper location in your file system, and
614            set the owner to be the same as the one that the Tomcat
615            server will be running as. Remember this location for
616            later use. The default location is <filename>/usr/local/base2/files</filename>.
617          </para>
618        </listitem>
619      </varlistentry>
620     
621      <varlistentry>
622        <term>BASE (plug-in setup)</term>
623        <listitem>
624          <para>
625            An area for plug-in and extensions installation must be setup.
626            Create an empty directory in a proper location in your file system,
627            and make sure that the user that the Tomcat
628            server will be running as has read permission. Remember this location for
629            later use. The default location is <filename>/usr/local/base2/plugins</filename>.
630          </para>
631        </listitem>
632      </varlistentry>
633
634      <varlistentry id="installation.main.configuration">
635        <term>BASE (configuration)</term>
636        <listitem>
637          <para>
638            Basic BASE configuration is done in
639            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>:
640            <itemizedlist>
641              <listitem>
642                Uncomment the database engine section that match your setup.
643              </listitem>
644              <listitem>
645                Modify the <emphasis>db.url</emphasis>,
646                <emphasis>db.dynamic.catalog</emphasis>,
647                <emphasis>db.username</emphasis>,
648                and <emphasis>db.password</emphasis> settings to match
649                your choice above. (<emphasis>database host and
650                database name (e.g. base2)</emphasis>,
651                <emphasis>e.g. base2dynamic</emphasis>,
652                <emphasis>db_user</emphasis>, and
653                <emphasis>db_password</emphasis>, respectively.)
654              </listitem>
655              <listitem>
656                Modify the <emphasis>userfiles</emphasis> setting to
657                match your choice in file storage setup above.
658              </listitem>
659              <listitem>
660                Modify the <emphasis>plugins.dir</emphasis> setting to
661                match your choice in plug-in setup above.
662              </listitem>
663            </itemizedlist>
664            See the <xref linkend="appendix.base.config"/> for more
665            information about the settings in
666            the <filename>base.config</filename> file.
667          </para>
668          <para>
669            <emphasis>Optional but recommended.</emphasis> You may want
670            to modify extended properties to fit your needs. Extended
671            properties are defined in
672            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/extended-properties.xml</filename>.
673            There is an
674            administrator <ulink
675            url="http://base.thep.lu.se/chrome/site/doc/historical/admin/extended-properties.html">document
676            discussing extended properties</ulink> available. If you
677            plan to perform a migration of a BASE version 1.2 database you
678            should probably not remove any extended properties
679            columns (this is not tested so the outcome is currently
680            undefined). However, adding columns does not affect
681            migration.
682          </para>
683        </listitem>
684      </varlistentry>
685
686      <varlistentry>
687        <term>BASE (database initialization)</term>
688        <listitem>
689          <para>
690            Change directory to
691            <filename class="directory">&lt;base-dir&gt;/bin</filename>
692            and execute the following commands:
693        <programlisting>
694./initdb.sh [base_root_login] base_root_password
695./updateindexes.sh
696</programlisting>
697
698            The second command is important for PostgreSQL users
699            since the Hibernate database initialisation utility
700            is not able to create all indexes that are required.
701            BASE will still work without the indexes but performance
702            may suffer.
703
704            <important>
705            <para>
706            The <emphasis>base_root_login</emphasis> and
707            <emphasis>base_root_password</emphasis> you use here
708            is given to the BASE web application root user account.
709            The <emphasis>base_root_login</emphasis> is optional. If
710            not specified, <constant>root</constant> is used for
711            the login.
712            </para>
713            </important>
714            If the initialisation script fail, it is most probably a
715            problem related to the underlying database. Make sure that
716            the database accepts network connection and make sure that
717            <emphasis>db_user</emphasis> has proper credentials.
718          </para>
719        </listitem>
720      </varlistentry>
721
722      <varlistentry>
723        <term>BASE and Tomcat</term>
724        <listitem>
725          <para>
726            Either move the <filename
727            class="directory">&lt;base-dir&gt;/www</filename> directory
728            to the Tomcat <filename class="directory">webapps</filename>
729            directory or create a symbolic link from the Tomcat
730            <filename class="directory">webapps</filename> directory to
731            the <filename class="directory">&lt;base-dir&gt;/www</filename>
732            directory
733<programlisting>cd /path/to/tomcat/webapps
734ln -s /path_to_base/www base2</programlisting>
735          </para>
736          <para>
737            If you plan to install extensions you should make sure that
738            the <filename class="directory">&lt;base-dir&gt;/www/extensions</filename>
739            directory is writable by the user account Tomcat is running as.
740          </para>
741          <para>
742            Start/restart Tomcat, and try http://hostname:8080/base2
743            (change <emphasis>hostname</emphasis> to your hostname) in
744            your favourite browser. The BASE log-in page should appear
745            after a few 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 initialization 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      utilize 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 dialogs
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 transfer 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>Unlimited</guilabel></term>
1279                <listitem>
1280                  <para>
1281                    Check this to not limit the transfer rate. In this case, the
1282                    Internet connection of the server is the limit.
1283                  </para>
1284                </listitem>
1285              </varlistentry>
1286            </variablelist>
1287          </helptext>
1288        </listitem>
1289      </varlistentry>
1290      <varlistentry>
1291        <term>
1292          <guilabel>About</guilabel>
1293        </term>
1294        <listitem>
1295          <helptext external_id="serverconfig.about"
1296            title="Information about the server">
1297            <variablelist>
1298              <varlistentry>
1299                <term><guilabel>Administrator name</guilabel></term>
1300                <listitem>
1301                  <para>
1302                    Name of the responsible administrator. The name is displayed
1303                    at the bottom of each page in BASE and in the about-dialog.
1304                  </para>
1305                </listitem>
1306              </varlistentry>
1307              <varlistentry>
1308                <term><guilabel>Administrator email</guilabel></term>
1309                <listitem>
1310                  <para>
1311                    An email which the administrator can be contacted on. The
1312                    administrator name, visible at the bottom of each page, will
1313                    be linked to this email address.
1314                  </para>
1315                </listitem>
1316              </varlistentry>
1317              <varlistentry>
1318                <term><guilabel>About</guilabel></term>
1319                <listitem>
1320                  <para>
1321                    Text written in this field is displayed in the
1322                    <guilabel>About this server</guilabel> section on the login
1323                    page and in the about-dialog window. We recommend changing the
1324                    default Latin text to something meaningful, or remove it
1325                    to hide the section completely.
1326                  </para>
1327                </listitem>
1328              </varlistentry>
1329            </variablelist>
1330          </helptext>
1331        </listitem>
1332      </varlistentry>
1333      <varlistentry>
1334        <term>
1335          <guilabel>Get account</guilabel>
1336        </term>
1337        <listitem>
1338          <helptext external_id="serverconfig.getaccount"
1339            title="Instructions to get an account">
1340            <para>
1341              A description what a user should do to get
1342              an account on the particular BASE server. This text is linked
1343              to the <guilabel>Get an account!</guilabel> link on the login
1344              page. We recommend that the Latin text is replaced with some useful
1345              information, or that it is removed to hide the link.
1346            </para>
1347          </helptext>
1348        </listitem>
1349      </varlistentry>
1350      <varlistentry>
1351        <term>
1352          <guilabel>Forgotten password</guilabel>
1353        </term>
1354        <listitem>
1355          <helptext external_id="serverconfig.password"
1356            title="Instructions when password is forgotten.">
1357            <para>
1358              A description what a user should do if the password is forgotten.
1359              This text is linked
1360              to the <guilabel>Forgot your password?</guilabel> link on the login
1361              page. We recommend that the Latin text is replaced with some useful
1362              information, or that it is removed to hide the link.
1363            </para>
1364          </helptext>
1365        </listitem>
1366      </varlistentry>
1367      <varlistentry>
1368        <term>
1369          <guilabel>Links</guilabel>
1370        </term>
1371        <listitem>
1372          <helptext external_id="serverconfig.links" title="Configurable links">
1373            <para>
1374              External configurable link-types inside BASE.
1375              <note>
1376                <para>
1377                  Only link-types that have been set will be visible in the web
1378                  client.
1379                </para>
1380              </note>
1381            </para>
1382            <variablelist>
1383              <varlistentry>
1384                <term><guilabel>Help</guilabel></term>
1385                <listitem>
1386                  <para>
1387                    Links to where the help text is located. By default
1388                    this is set to the documentation for the latest released
1389                    BASE version on the BASE web site,
1390                    <ulink
1391                      url="http://base.thep.lu.se/chrome/site/doc/html/index.html">
1392                      http://base.thep.lu.se/chrome/site/doc/html/index.html</ulink>.
1393                   
1394                    If you want the documentation for a specific version you will
1395                    have to setup a site for that yourself and then change the link
1396                    to that site. The documentation is included in the downloaded package
1397                    in the directory <filename>&lt;basedir&gt;/doc/html</filename>.
1398                  </para>
1399                </listitem>
1400              </varlistentry>
1401              <varlistentry>
1402                <term>
1403                  <guilabel>FAQ</guilabel>
1404                </term>
1405                <listitem>
1406                  <para>Where frequently asked questions can be found. Empty by default.</para>
1407                </listitem>
1408              </varlistentry>
1409              <varlistentry>
1410                <term>
1411                  <guilabel>Report a bug</guilabel>
1412                </term>
1413                <listitem>
1414                  <para>
1415                    Where the user could report bugs, feature request or
1416                    perhaps other feedback that concerns the program. As default
1417                    this is set to the feedback section on BASE web site,
1418                    <ulink url="http://base.thep.lu.se/#Feedback">http://base.thep.lu.se/#Feedback</ulink>.
1419                    Note that users must login in order to submit information.
1420                  </para>
1421                </listitem>
1422              </varlistentry>
1423            </variablelist>
1424          </helptext>
1425        </listitem>
1426      </varlistentry>
1427    </variablelist>
1428   
1429    <sect2 id="installation.broadcast">
1430      <title>Sending a broadcast message to logged in users</title>
1431
1432      <para>
1433        It is possible to send a message to all logged in user.
1434        Open the
1435        <menuchoice>
1436          <guimenu>Administrate</guimenu>
1437          <guimenuitem>Broadcast message</guimenuitem>
1438        </menuchoice> dialog box.
1439      </para>
1440     
1441      <figure id="installation.figures.broadcast">
1442        <title>Broadcast message</title>
1443        <screenshot>
1444          <mediaobject>
1445            <imageobject><imagedata 
1446              fileref="figures/broadcast_message.png" format="PNG"
1447              /></imageobject>
1448          </mediaobject>
1449        </screenshot>
1450      </figure>
1451     
1452      <helptext external_id="broadcast.message" title="Broadcast message">
1453        <para>
1454        This dialog allows you to specify a message that is sent to all
1455        logged in users as well as on the login form. It is also possible
1456        to "disable" login.
1457        </para>
1458        <variablelist>
1459        <varlistentry>
1460          <term><guilabel>Title</guilabel></term>
1461          <listitem>
1462            <para>
1463            The title of the message. It should be a short and concise to
1464            avoid confusion. The title will be displayed on a lot of places
1465            and a user may have to click on it to read the more detailed
1466            message.
1467            </para>
1468          </listitem>
1469        </varlistentry>
1470        <varlistentry>
1471          <term><guilabel>Disable login</guilabel></term>
1472          <listitem>
1473            <para>
1474            Mark this check-box to try to prevent new users from logging in. To
1475            avoid problems that can be caused by blocking the server admin out,
1476            the login is not completely disabled. Any user can still login but
1477            only after by-passing several warnings.
1478            </para>
1479          </listitem>
1480        </varlistentry>
1481        <varlistentry>
1482          <term><guilabel>Message</guilabel></term>
1483          <listitem>
1484            <para>
1485            If needed, a longer message giving more information. Users may
1486            have to click on a link to be able to see the complete message.
1487            </para>
1488          </listitem>
1489        </varlistentry>
1490        </variablelist>
1491       
1492        <note>
1493          The message will be enabled until it is manually removed by saving
1494          an empty form, or until the Tomcat server is restarted. Since the
1495          message is only kept in memory, a restart will always remove it.
1496        </note>
1497     
1498      </helptext>
1499     
1500    </sect2>
1501   
1502  </sect1>
1503
1504</chapter>
Note: See TracBrowser for help on using the repository browser.