Changeset 6327


Ignore:
Timestamp:
Sep 16, 2013, 3:47:01 PM (9 years ago)
Author:
Jari Häkkinen
Message:

Addresses #1769. Re-committing the changes reverted in r6326, with Nicklas edits retained.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/admin/installation.xml

    r6326 r6327  
    99  Copyright (C) 2008 Jari Häkkinen, Nicklas Nordborg, Martin Svensson
    1010  Copyright (C) 2009 Jari Häkkinen, Nicklas Nordborg
     11  Copyright (C) 2010, 2011, 2012 Nicklas Nordborg
     12  Copyright (C) 2013 Jari Häkkinen, Nicklas Nordborg
    1113
    1214  This file is part of BASE - BioArray Software Environment.
     
    5456      </para>
    5557     
    56       <bridgehead>Java SE 7 and Tomcat 7 is required</bridgehead>
     58      <bridgehead>Java SE 7 and Tomcat 7 are required</bridgehead>
    5759      <para>
    5860        BASE now require <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java SE 7</ulink>
     
    256258            </para>
    257259          </important>
    258          
    259         </listitem>
    260       </varlistentry>
    261 
    262       <varlistentry>
    263         <term>Tomcat</term>
    264         <listitem>
    265           <para>
    266             Download and install Apache Tomcat 7.0.30 or any later 7.x release,
    267             available from <ulink url="http://tomcat.apache.org" />.
    268           </para>
    269          
    270           <important>
    271             <para>
    272             As of BASE 3.3 Tomcat 7 is required. BASE will no longer run on
    273             Tomcat 6 or lower.
    274             </para>
    275           </important>
    276          
    277           <para>
    278             There are a few configuration options that are needed to
    279             make Tomcat work properly with BASE. The options are set in the
    280             <code>CATALINA_OPTS</code> environment variable.
    281           </para>
    282          
    283           <itemizedlist>
    284             <listitem>
    285               <para>
    286                 Increase the amount of memory that Tomcat is allowed to use. The default setting is
    287                 usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>.
    288               </para>
    289             </listitem>
    290             <listitem>
    291               <para>
    292                 Disable strict parsing of JSP files.
    293                 <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code>
    294               </para>
    295             </listitem>
    296             <listitem>
    297               <para>
    298                 Unless you have manually downloaded and installed JAI (Java Advanced
    299                 Imaging) native acceleration libraries (see <ulink
    300                 url="http://java.sun.com/javase/technologies/desktop/media/jai/" />)
    301                 it is a good idea to disable the native acceleration of JAI.
    302                 <code>-Dcom.sun.media.jai.disableMediaLib=true</code>
    303               </para>
    304             </listitem>
    305             <listitem>
    306               <para>
    307                 Enable headless mode if your are setting up a server which doesn't have
    308                 a display device connected to it. <code>-Djava.awt.headless=true</code>.
    309               </para>
    310             </listitem>
    311          
    312           </itemizedlist>
    313          
    314           <para>
    315             Depending on your system there are probably several ways to set the
    316             the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following
    317             line (as a single line) close to the top of the <filename>catalina.sh</filename>
    318             script that comes with Tomcat (directory <filename
    319             class="directory">bin</filename>):
    320 <programlisting>CATALINA_OPTS="-Xmx1G
    321 -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
    322 -Dcom.sun.media.jai.disableMediaLib=true
    323 -Djava.awt.headless=true"</programlisting>
    324           </para>
    325           <para>
    326             For more information about Tomcat options see
    327             <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/index.html" />.
    328           </para>
     260
    329261        </listitem>
    330262      </varlistentry>
     
    335267          <para>
    336268            BASE
    337             utilize <ulink
     269            utilise <ulink
    338270            url="http://www.hibernate.org/">Hibernate</ulink> for
    339271            object persistence to a relational database. Hibernate
     
    383315      </varlistentry>
    384316
    385       <varlistentry>
    386         <term>BASE (download and unpacking)</term>
    387         <listitem>
    388           <para>
    389             <ulink
    390             url="http://base.thep.lu.se/wiki/DownloadPage">Download
    391             BASE</ulink> and unpack the downloaded file,
    392             i.e. <command>tar zxpf base-...tar.gz</command>. If you
    393             prefer to have the bleeding edge version of BASE, perform
    394             a checkout of the source from the subversion repository
    395             (subversion checkout instructions at
    396             <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
    397             trac site</ulink>).
    398           </para>
    399           <para>
    400             If you choose to download the binary package, skip to the
    401             next item. The rest of us, read on and compile BASE. If
    402             you downloaded a source distribution, unpack the
    403             downloaded file <command>tar zxpf
    404             base-...src.tar.gz</command>, or you may have performed a
    405             subversion checkout.  Change to the 'root' base2
    406             directory, and issue <command>ant
    407             package.bin</command>. This will create a binary package
    408             in the base2 'root' directory. Unpack this new package
    409             (outside of the source file hierarchy), and from now on
    410             the instructions are the same irrespective where you got
    411             the binary package.
    412           </para>
    413           <para>
    414             <emphasis>This section is intended for advanced users and
    415               programmers only. In cases when you want to change the
    416               BASE code and try out personalized features it may be
    417               advantageous to run the tweaked BASE server against the
    418               development tree. Instructions on how to accomplish this
    419               is available in the
    420               <ulink
    421               url="http://base.thep.lu.se/wiki/BuildingBase">building
    422               BASE document</ulink>. When you return back after
    423               compiling in the subversion tree you can follow the
    424               instruction here (with obvious changes to
    425               paths).</emphasis>
    426           </para>
    427         </listitem>
    428       </varlistentry>
    429 
    430317      <varlistentry id="installation.main.database">
    431318        <term>BASE (database engine)</term>
    432319        <listitem>
    433320          <para>
    434             Instructions for MySQL and PostgreSQL are available
    435             below. The database names (base2 and base2dynamic is used
    436             here), the <emphasis>db_user</emphasis>, and
    437             the <emphasis>db_password</emphasis> can be changed during
    438             the creation of the databases. It is recommended to change
    439             the <emphasis>db_password</emphasis>, the other changes
    440             can be made if desired. The database names,
    441             the <emphasis>db_user</emphasis>, and
    442             the <emphasis>db_password</emphasis> are needed in a later
    443             step below when configuring BASE.
     321            The database names (base2 and base2dynamic are used here),
     322            the <emphasis>db_user</emphasis>, and the
     323            <emphasis>db_password</emphasis> can be changed during the
     324            creation of the databases. It is recommended to change the
     325            <emphasis>db_password</emphasis>, the other changes are
     326            optional and can be made if desired. The database names,
     327            the <emphasis>db_user</emphasis>, and the
     328            <emphasis>db_password</emphasis> are needed below when
     329            configuring BASE.
    444330          </para>
    445331          <note>
    446             Note that the <emphasis>db_user</emphasis> name
    447             and <emphasis>db_password</emphasis> set here is used
     332            Note that the <emphasis>db_user</emphasis> name and
     333            <emphasis>db_password</emphasis> set here is used
    448334            internally by BASE in communication with the database and
    449335            is never used to log on to the BASE application.
     
    453339            <para>
    454340              Otherwise there will be a problem with storing values
    455               that uses characters outside the normal Latin1 range, for
    456               example unit-related such as µ (micro) and Ω (ohm).
     341              that uses characters outside the normal Latin1 range,
     342              for example unit-related such as µ (micro) and Ω (ohm).
    457343            </para>
    458344          </important>
     
    477363                </para>             
    478364                <para>
    479                   The <filename>&lt;base-dir&gt;/misc/sql/createdb.mysql.sql</filename>
    480                   file contains the above statements and can be used
     365                  If you download BASE (instructions below) you find a file
     366                  <filename>&lt;base-dir&gt;/misc/sql/createdb.mysql.sql</filename>
     367                  that contains the above statements and can be used
    481368                  by the <filename>mysql</filename> command-line tool
    482                   (remember to edit
    483                   the <emphasis>db_user</emphasis>,
    484                   <emphasis>db_password</emphasis>,
    485                   and the database names in the script file before
    486                   executing the command): <command>mysql -uroot -p
    487                   &lt; ./misc/sql/createdb.mysql.sql</command>. The
     369                  (remember to edit the <emphasis>db_user</emphasis>,
     370                  <emphasis>db_password</emphasis>, and the database
     371                  names in the script file before executing the
     372                  command): <command>mysql -uroot -p &lt;
     373                  &lt;base-dir&gt;/misc/sql/createdb.mysql.sql</command>. The
    488374                  header in the script file contains further
    489375                  information about the script.
     
    507393  # within the tool and quit with a '\q'.
    508394CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting>
    509                   The <filename>&lt;base-dir&gt;/misc/sql/createdb.postgresql.sql</filename>
    510                   file contains the above statements and can be used
     395
     396                  If you download BASE (instructions below) you find a file
     397                  <filename>&lt;base-dir&gt;/misc/sql/createdb.postgresql.sql</filename>
     398                  that contains the above statements and can be used
    511399                  by the <filename>psql</filename> command-line tool:
    512                   <command>psql -f ./misc/sql/createdb.posgres.sql
    513                     template1</command> The header in the script file
     400                  <command>psql -f
     401                  &lt;base-dir&gt;/misc/sql/createdb.posgres.sql
     402                  template1</command> The header in the script file
    514403                  contains further information about the script.
    515404                </para>
     
    521410
    522411      <varlistentry>
     412        <term>BASE (download and unpacking)</term>
     413        <listitem>
     414          <para>
     415            <ulink
     416            url="http://base.thep.lu.se/wiki/DownloadPage">Download
     417            BASE</ulink> and unpack the downloaded file,
     418            i.e. <command>tar zxpf base-...tar.gz</command>. If you
     419            prefer to have the bleeding edge version of BASE, perform
     420            a checkout of the source from the subversion repository
     421            (subversion checkout instructions at
     422            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
     423            trac site</ulink>).
     424          </para>
     425          <para>
     426            If you choose to download the binary package, skip to the
     427            next item. The rest of us, read on and compile BASE. If
     428            you downloaded a source distribution, unpack the
     429            downloaded file <command>tar zxpf
     430            base-...src.tar.gz</command>, or you may have performed a
     431            subversion checkout.  Change to the 'root' base2
     432            directory, and issue <command>ant
     433            package.bin</command>. This will create a binary package
     434            in the base2 'root' directory. Unpack this new package
     435            (outside of the source file hierarchy), and from now on
     436            the instructions are the same irrespective where you got
     437            the binary package.
     438          </para>
     439          <para>
     440            <emphasis>This section is intended for advanced users and
     441              programmers only. In cases when you want to change the
     442              BASE code and try out personalised features it may be
     443              advantageous to run the tweaked BASE server against the
     444              development tree. Instructions on how to accomplish this
     445              is available in the
     446              <ulink
     447              url="http://base.thep.lu.se/wiki/BuildingBase">building
     448              BASE document</ulink>. When you return back after
     449              compiling in the subversion tree you can follow the
     450              instruction here (with obvious changes to
     451              paths).</emphasis>
     452          </para>
     453        </listitem>
     454      </varlistentry>
     455
     456      <varlistentry>
    523457        <term>BASE (file storage setup)</term>
    524458        <listitem>
    525459          <para>
    526460            An area for file storage must be setup. Create an empty
    527             directory in a proper location in your file system, and
    528             set the owner to be the same as the one that the Tomcat
    529             server will be running as. Remember this location for
     461            directory in a proper location in your file system. Set
     462            the owner of the created directory to the user the Tomcat
     463            server will be running as. Tomcat server set up
     464            instructions will follow below. Remember this location for
    530465            later use. The default location is <filename>/usr/local/base2/files</filename>.
    531466          </para>
     
    540475            Create an empty directory in a proper location in your file system,
    541476            and make sure that the user that the Tomcat
    542             server will be running as has read permission. Remember this location for
     477            server will be running as has read permission in this
     478            directory. Tomcat server set up instructions will follow
     479            below. Remember this location for
    543480            later use. The default location is <filename>/usr/local/base2/plugins</filename>.
    544481          </para>
     
    599536
    600537      <varlistentry>
    601         <term>BASE (database initialization)</term>
     538        <term>BASE (database initialisation)</term>
    602539        <listitem>
    603540          <para>
     
    606543            and execute the following commands:
    607544        <programlisting>
    608 ./initdb.sh [base_root_login] base_root_password
     545sudo ./initdb.sh [base_root_login] base_root_password
    609546./updateindexes.sh
    610547</programlisting>
    611 
    612             The second command is important for PostgreSQL users
    613             since the Hibernate database initialisation utility
    614             is not able to create all indexes that are required.
    615             BASE will still work without the indexes but performance
    616             may suffer.
     548          </para>
     549
     550          <para>
     551            In the first command sudo is required because a file will
     552            be created in the directory defined by
     553            <emphasis>userfiles</emphasis> above. If the directory is
     554            writable by you then sudo is not needed.
     555          </para>
     556
     557          <para>
     558            The second command is important for PostgreSQL users since
     559            the Hibernate database initialisation utility is not able
     560            to create all required indexes. BASE will work without the
     561            indexes but performance is impaired. Running the script as
     562            a MySQL user does not have a negative impact.
     563          </para>
    617564
    618565            <important>
     
    626573            </para>
    627574            </important>
    628             If the initialisation script fail, it is most probably a
     575
     576          <para>
     577            If the initialisation script fails, it is probably a
    629578            problem related to the underlying database. Make sure that
    630579            the database accepts network connection and make sure that
    631             <emphasis>db_user</emphasis> has proper credentials.
     580            <emphasis>db_user</emphasis> has proper credentials. You
     581            may also get a <emphasis>Permission denied</emphasis> on
     582            file <filename>extension-settings.xml</filename> if you do
     583            not have write permission to the directory defined by
     584            variable <emphasis>userfiles</emphasis> in file
     585            <filename>base.config</filename>. If the initialisation
     586            fails on <filename>extension-settings.xml</filename> you
     587            must drop the database and recreate the database as
     588            described in <xref linkend="installation.main.database"/>.
     589          </para>
     590        </listitem>
     591      </varlistentry>
     592
     593      <varlistentry>
     594        <term>Tomcat</term>
     595        <listitem>
     596          <para>
     597            Download and install Apache Tomcat 7.0.30 or any later 7.x
     598            release, available from <ulink url="http://tomcat.apache.org" />.
     599          </para>
     600
     601          <important>
     602            <para>
     603              As of BASE 3.3 Tomcat 7 is required. BASE will no longer
     604              run on Tomcat 6 or lower.
     605            </para>
     606          </important>
     607
     608          <para>
     609            There are a few configuration options that are needed to
     610            make Tomcat work properly with BASE. The options are set in the
     611            <code>CATALINA_OPTS</code> environment variable.
     612          </para>
     613         
     614          <itemizedlist>
     615            <listitem>
     616              <para>
     617                Increase the amount of memory that Tomcat is allowed to use. The default setting is
     618                usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>.
     619              </para>
     620            </listitem>
     621            <listitem>
     622              <para>
     623                Disable strict parsing of JSP files.
     624                <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code>
     625              </para>
     626            </listitem>
     627            <listitem>
     628              <para>
     629                Unless you have manually downloaded and installed JAI (Java Advanced
     630                Imaging) native acceleration libraries (see <ulink
     631                url="http://java.sun.com/javase/technologies/desktop/media/jai/" />)
     632                it is a good idea to disable the native acceleration of JAI.
     633                <code>-Dcom.sun.media.jai.disableMediaLib=true</code>
     634              </para>
     635            </listitem>
     636            <listitem>
     637              <para>
     638                Enable headless mode if your are setting up a server which doesn't have
     639                a display device connected to it. <code>-Djava.awt.headless=true</code>.
     640              </para>
     641            </listitem>
     642          </itemizedlist>
     643         
     644          <para>
     645            Depending on your system there are probably several ways to set the
     646            the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following
     647            line (as a single line) close to the top of the <filename>catalina.sh</filename>
     648            script that comes with Tomcat (directory <filename
     649            class="directory">bin</filename>):
     650<programlisting>CATALINA_OPTS="-Xmx1G
     651-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
     652-Dcom.sun.media.jai.disableMediaLib=true
     653-Djava.awt.headless=true"</programlisting>
     654          </para>
     655          <para>
     656            For more information about Tomcat options see
     657            <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/index.html" />.
    632658          </para>
    633659        </listitem>
     
    638664        <listitem>
    639665          <para>
    640             Either move the <filename
    641             class="directory">&lt;base-dir&gt;/www</filename> directory
    642             to the Tomcat <filename class="directory">webapps</filename>
    643             directory or create a symbolic link from the Tomcat
    644             <filename class="directory">webapps</filename> directory to
    645             the <filename class="directory">&lt;base-dir&gt;/www</filename>
    646             directory
     666            Do the following:
     667            <itemizedlist>
     668              <listitem>
     669                <para>
     670                  Either move the <filename
     671                  class="directory">&lt;base-dir&gt;/www</filename>
     672                  directory to the Tomcat <filename
     673                  class="directory">webapps</filename> directory or
     674                  create a symbolic link from the Tomcat <filename
     675                  class="directory">webapps</filename> directory to
     676                  the <filename
     677                  class="directory">&lt;base-dir&gt;/www</filename>
     678                  directory
    647679<programlisting>cd /path/to/tomcat/webapps
    648680ln -s /path_to_base/www base2</programlisting>
    649           </para>
    650           <para>
    651             If you plan to install extensions you should make sure that
    652             the <filename class="directory">&lt;base-dir&gt;/www/extensions</filename>
    653             directory is writable by the user account Tomcat is running as.
    654           </para>
    655           <para>
    656             Start/restart Tomcat, and try http://hostname:8080/base2
    657             (change <emphasis>hostname</emphasis> to your hostname) in
    658             your favourite browser. The BASE log-in page should appear
    659             after a few seconds.
     681                </para>
     682              </listitem>
     683              <listitem>
     684                <para>
     685                  Make sure that user Tomcat is running as can read
     686                  all objects in the directory defined by
     687                  <emphasis>plugins.dir</emphasis> in file
     688                  <filename>base.config</filename>.
     689                </para>
     690              </listitem>
     691              <listitem>
     692                <para>
     693                  Make sure that user Tomcat is running as owns (i.e.,
     694                  can read, write, delete and create) all objects in
     695                  the directory, as well as the directory itself,
     696                  defined by <emphasis>userfiles</emphasis> in file
     697                  <filename>base.config</filename>.
     698                </para>
     699              </listitem>
     700              <listitem>
     701                <para>
     702                  If you plan to install extensions you should make
     703                  sure that the <filename
     704                  class="directory">&lt;base-dir&gt;/www/extensions</filename>
     705                  directory is writable by the user account Tomcat is
     706                  running as.
     707                </para>
     708              </listitem>
     709            </itemizedlist>
     710          </para>
     711          <para>
     712            and finalise with start, or restart, Tomcat, and try
     713            http://hostname:8080/base2 (change
     714            <emphasis>hostname</emphasis> to your hostname and
     715            <emphasis>base2</emphasis> if you selected another name
     716            for the BASE Tomcat application) in your favourite
     717            browser. The BASE log-in page should appear after a few
     718            seconds.
    660719          </para>
    661720        </listitem>
     
    687746            user <emphasis>root</emphasis> (use
    688747            the <emphasis>base_root_password</emphasis> from the
    689             database initialization step above). You should begin with
     748            database initialisation step above). You should begin with
    690749            creating a couple user accounts, for more information on
    691750            how to create user accounts please refer to
     
    724783      are optional and must be installed and setup
    725784      separately. However, BASE is prepared for job agent setup and to
    726       utilize the agents, but the agent are not required.
     785      utilise the agents, but the agent are not required.
    727786    </para>
    728787
     
    10231082          agents</guilabel> tab. To do the same from the job agent pages,
    10241083          go to the edit view of the job agent and select
    1025           the <guilabel>Plugins</guilabel> tab. The registration dialogs
     1084          the <guilabel>Plugins</guilabel> tab. The registration dialogues
    10261085          are very similar but only the plug-in side of registration is
    10271086          described here. The major difference is that it is not possible
     
    14331492      It is possible to migrate a BASE installation on a MySQL database to a
    14341493      PostgreSQL database. In a real-world scenario a migration is probably coupled
    1435       with a hardware upgrade, ie. the MySQL installation is on one (the old) server
     1494      with a hardware upgrade, i.e. the MySQL installation is on one (the old) server
    14361495      and the PostgreSQL installation is on another (the new) server. While
    14371496      this is not any problem per se, it requires a few extra steps to ensure that
     
    15521611              directories.
    15531612              The import program protects against some mistakes by comparing
    1554               the colum names from the export with the column names in the new
     1613              the column names from the export with the column names in the new
    15551614              database, but it will, for example, not check that data types match.
    15561615              </para>
Note: See TracChangeset for help on using the changeset viewer.