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

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

References #2033 and #2034. Added a note about the changes to the list of update warnings and incompatible changes.

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