doc/src/docbook/admin/installation.xml

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