source: branches/3.4-stable/doc/src/docbook/admin/installation.xml @ 6670

Last change on this file since 6670 was 6670, checked in by Nicklas Nordborg, 7 years ago

References #1742: Upgrade to Hibernate 4.x

Updated documentation. The updateindexes.sh is now important for both MySQL and PostgreSQL.

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