Changeset 3299


Ignore:
Timestamp:
May 7, 2007, 3:13:27 PM (14 years ago)
Author:
Jari Häkkinen
Message:

Addresses #516.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/admindoc/installation_upgrade.xml

    r3292 r3299  
    3131
    3232  <title>Installation, migration, and upgrade instructions</title>
     33
     34  <note>
     35    These instructions apply only to the BASE release which this
     36    document is a part of.
     37  </note>
    3338
    3439  <para>
    … …  
    4954  </para>
    5055
    51   <note>
    52     These instructions apply only to the BASE release which this
    53     document is a part of.
    54   </note>
    55 
    56     <sect1 id="installation_upgrade.upgrade">
    57       <title>Upgrade instructions</title>
    58 
    59       <important>
    60         Note to PostgreSQL users: Upgrading BASE to versions earlier
    61         than v2.2 is not be safe with an PostgreSQL database engine
    62         due to a bug in Hibernate. The problem is reported to
    63         Hibernate developers. There now exists a workaround for this
    64         problem. Read more about the workaround on
    65         the <ulink
    66         url="http://base.thep.lu.se/wiki/UpgradePostgres">Upgrading a
    67         Postgres database prior to BASE 2.2</ulink> page. This fix is
    68         not needed for the release which this document is a part of.
    69       </important>
    70 
    71       <para>
    72         As always, backup your database before attempting an
    73         upgrade. The BASE team performs extensive testing before
    74         releasing a new version of BASE but there are always a
    75         possibility for unexpected events during upgrades. In upgrades
    76         requiring a change in the underlying database there is no
    77         (supported) way to revert to a previous version of BASE using
    78         BASE tools, you need to use your backup for this use case.
    79       </para>
    80 
    81       <para>
    82         The strategy here is to install the new BASE release to
    83         another directory than the one in use. This requires transfer
    84         of configuration settings to the new install but more on that
    85         below.
    86       </para>
    87 
    88       <variablelist>
    89         <varlistentry>
    90           <term>Shut down the tomcat server</term>
    91           <listitem>
    92             <para>
    93               If the BASE application is not shut down already, it is
    94               time to do it now. Do something like <command>sudo
    95               /etc/init.d/tomcat5.5 stop</command>
    96             </para>
    97           </listitem>
    98         </varlistentry>
    99 
    100         <varlistentry>
    101           <term>Rename your current server</term>
    102           <listitem>
    103             <para>
    104               Rename your current BASE 2 installation <command>mv
    105                 /path/to/base /path/to/base_old</command>.
    106             </para>
    107           </listitem>
    108         </varlistentry>
    109 
    110         <varlistentry>
    111           <term>Download and unpack BASE</term>
    112           <listitem>
    113             <para>
    114               There are severeal ways to download BASE. Please refer
    115               to section
    116               <xref linkend="resources.home_page.download"/> for
    117               information on downloading BASE, and select the item
    118               matching your download option:
    119             </para>
    120 
    121             <variablelist>
    122               <varlistentry>
    123                 <term><emphasis>Pre-compiled package</emphasis></term>
    124                 <listitem>
    125                   <para>
    126                     If you selected to download a pre-compiled
    127                     package, unpack the downloaded file
    128                     with <command>tar zxpf base-...tar.gz</command>.
    129                   </para>
    130                 </listitem>
    131               </varlistentry>
    132 
    133               <varlistentry>
    134                 <term><emphasis>Source package</emphasis></term>
    135                 <listitem>
    136                   <para>
    137                     If you selected to download a source package,
    138                     unpack the downloaded file with <command>tar zxpf
    139                     base-...src.tar.gz</command>. Change to the new
    140                     direcotry, and issue <command>ant
    141                     package.bin</command>. This will create a binary
    142                     package in the current directory. Unpack this new
    143                     package (outside of the source file hierarchy).
    144                   </para>
    145                 </listitem>
    146               </varlistentry>
    147 
    148               <varlistentry>
    149                 <term><emphasis>Subversion checkout</emphasis></term>
    150                 <listitem>
    151                   <para>
    152                     This option is for advanced users only and is not
    153                     covered here. Please refer
    154                     to <ulink
    155                     url="http://base.thep.lu.se/chrome/site/doc/development/build.html">the
    156                     builing BASE document</ulink> for information on
    157                     this download option.
    158                   </para>
    159                 </listitem>
    160               </varlistentry>
    161 
    162             </variablelist>
    163           </listitem>
    164 
    165         </varlistentry>
    166 
    167         <varlistentry>
    168           <term>Transfer files and settings</term>
    169           <listitem>
    170             <para>
    171               Settings from the previous installation must be
    172               transferred to the new installation. This is most easily
    173               done by comparing the configuration files from the
    174               previous install with the new files. Do not just copy
    175               the old files to the new install since new options may
    176               have appeared.
    177             </para>
    178             <para>
    179               In the main BASE configuration file,
    180               <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>,
    181               fields that needs to be transferred are usually
    182               <emphasis>db.username</emphasis>,
    183               <emphasis>db.password</emphasis>,
    184               and <emphasis>userfiles</emphasis>.
    185             </para>
    186             <para>
    187               Local settings in the raw data
    188               tables, <filename>/path/to/base/www/WEB-INF/classes/raw-data-types.xml</filename>,
    189               may need to be transferred.
    190             </para>
    191           </listitem>
    192         </varlistentry>
    193 
    194         <varlistentry>
    195           <term>Updating database schema</term>
    196           <listitem>
    197             <para>
    198               It is recommended that you also perform an update of
    199               your database schema.  Running the update scripts are
    200               not always necessary when upgrading BASE, but the
    201               running the update scripts are safe even in cases when
    202               there is no need to run them. Change directory
    203               to <filename
    204               class="direcotry">/path/to/base/bin/</filename> and
    205               issue
    206               <command>
    207                 <literallayout>sh ./updatedb.sh <emphasis>base_root_password</emphasis>
    208                 sh ./updateindexes.sh <emphasis>base_root_password</emphasis></literallayout>
    209               </command>
    210               where <emphasis>base_root_password</emphasis> is the
    211               password for the root user account within the BASE
    212               application.
    213             </para>
    214           </listitem>
    215         </varlistentry>
    216 
    217         <varlistentry>
    218           <term>Remove tomcat cache</term>
    219           <listitem>
    220             <para>
    221               As tomcat user, remove cached files and directories. Do
    222               something like
    223               <command>
    224                 <literallayout>cd /usr/share/apache-tomcat-5.5.15/
    225                 rm -rf work/Catalina</literallayout>
    226               </command>
    227             </para>
    228           </listitem>
    229         </varlistentry>
    230 
    231         <varlistentry>
    232           <term>Start tomcat</term>
    233           <listitem>
    234             <para>
    235               Start the tomcat server:
    236               <command>
    237                 <literallayout>sudo /etc/init.d/tomcat5.5 start</literallayout>
    238               </command>
    239             </para>
    240           </listitem>
    241         </varlistentry>
    242 
    243       </variablelist>
    244 
    245       <para>
    246         Done! Upgrade of BASE is finished.
    247       </para>
    248 
    249     </sect1>      <!-- Upgrade instructions -->
    250 
    251 
    252     <sect1 id="installation_upgrade.isntallation">
    253       <title>Installation instructions</title>
    254       <para></para>
    255     </sect1>
    256 
    257 
    258     <sect1 id="installation_upgrade.migration">
    259       <title>Migration instructions</title>
    260       <para></para>
    261     </sect1>
     56  <para>
     57    The instructions here assume
     58    that <ulink url="http://tomcat.apache.org/">tomcat</ulink> is used
     59    on the server side. Other servlet engines may work but we only
     60    test tomcat.
     61  </para>
     62
     63
     64  <sect1 id="installation_upgrade.upgrade">
     65    <title>Upgrade instructions</title>
     66
     67    <important>
     68      Note to PostgreSQL users: Upgrading BASE to versions earlier
     69      than v2.2 is not be safe with an PostgreSQL database engine due
     70      to a bug in Hibernate. The problem is reported to Hibernate
     71      developers. There now exists a workaround for this problem. Read
     72      more about the workaround on
     73      the <ulink
     74      url="http://base.thep.lu.se/wiki/UpgradePostgres">Upgrading a
     75      Postgres database prior to BASE 2.2</ulink> page. This fix is
     76      not needed for the release which this document is a part of.
     77    </important>
     78
     79    <para>
     80      As always, backup your database before attempting an
     81      upgrade. The BASE team performs extensive testing before
     82      releasing a new version of BASE but there are always a
     83      possibility for unexpected events during upgrades. In upgrades
     84      requiring a change in the underlying database there is no
     85      (supported) way to revert to a previous version of BASE using
     86      BASE tools, you need to use your backup for this use case.
     87    </para>
     88
     89    <para>
     90      The strategy here is to install the new BASE release to another
     91      directory than the one in use. This requires transfer of
     92      configuration settings to the new install but more on that
     93      below.
     94    </para>
     95
     96    <variablelist>
     97      <varlistentry>
     98        <term>Shut down the tomcat server</term>
     99        <listitem>
     100          <para>
     101            If the BASE application is not shut down already, it is
     102            time to do it now. Do something like <command>sudo
     103            /etc/init.d/tomcat5.5 stop</command>
     104          </para>
     105        </listitem>
     106      </varlistentry>
     107
     108      <varlistentry>
     109        <term>Rename your current server</term>
     110        <listitem>
     111          <para>
     112            Rename your current BASE 2 installation <command>mv
     113              /path/to/base /path/to/base_old</command>.
     114          </para>
     115        </listitem>
     116      </varlistentry>
     117
     118      <varlistentry>
     119        <term>Download and unpack BASE</term>
     120        <listitem>
     121          <para>
     122            There are severeal ways to download BASE. Please refer to
     123            section <xref linkend="resources.home_page.download"/> for
     124            information on downloading BASE, and select the item
     125            matching your download option:
     126          </para>
     127
     128          <variablelist>
     129            <varlistentry>
     130              <term><emphasis>Pre-compiled package</emphasis></term>
     131              <listitem>
     132                <para>
     133                  If you selected to download a pre-compiled package,
     134                  unpack the downloaded file with <command>tar zxpf
     135                  base-...tar.gz</command>.
     136                </para>
     137              </listitem>
     138            </varlistentry>
     139
     140            <varlistentry>
     141              <term><emphasis>Source package</emphasis></term>
     142              <listitem>
     143                <para>
     144                  If you selected to download a source package, unpack
     145                  the downloaded file with <command>tar zxpf
     146                  base-...src.tar.gz</command>. Change to the new
     147                  direcotry, and issue <command>ant
     148                  package.bin</command>. This will create a binary
     149                  package in the current directory. Unpack this new
     150                  package (outside of the source file hierarchy).
     151                </para>
     152              </listitem>
     153            </varlistentry>
     154
     155            <varlistentry>
     156              <term><emphasis>Subversion checkout</emphasis></term>
     157              <listitem>
     158                <para>
     159                  This option is for advanced users only and is not
     160                  covered here. Please refer
     161                  to <ulink
     162                  url="http://base.thep.lu.se/chrome/site/doc/development/build.html">the
     163                  builing BASE document</ulink> for information on
     164                  this download option.
     165                </para>
     166              </listitem>
     167            </varlistentry>
     168
     169          </variablelist>
     170        </listitem>
     171
     172      </varlistentry>
     173
     174      <varlistentry>
     175        <term>Transfer files and settings</term>
     176        <listitem>
     177          <para>
     178            Settings from the previous installation must be
     179            transferred to the new installation. This is most easily
     180            done by comparing the configuration files from the
     181            previous install with the new files. Do not just copy the
     182            old files to the new install since new options may have
     183            appeared.
     184          </para>
     185          <para>
     186            In the main BASE configuration file,
     187            <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>,
     188            fields that needs to be transferred are usually
     189            <emphasis>db.username</emphasis>,
     190            <emphasis>db.password</emphasis>,
     191            and <emphasis>userfiles</emphasis>.
     192          </para>
     193          <para>
     194            Local settings in the raw data
     195            tables, <filename>/path/to/base/www/WEB-INF/classes/raw-data-types.xml</filename>,
     196            may need to be transferred.
     197          </para>
     198        </listitem>
     199      </varlistentry>
     200
     201      <varlistentry>
     202        <term>Updating database schema</term>
     203        <listitem>
     204          <para>
     205            It is recommended that you also perform an update of your
     206            database schema.  Running the update scripts are not
     207            always necessary when upgrading BASE, but the running the
     208            update scripts are safe even in cases when there is no
     209            need to run them. Change directory
     210            to <filename
     211            class="direcotry">/path/to/base/bin/</filename> and issue
     212            <programlisting>
     213sh ./updatedb.sh <emphasis>base_root_password</emphasis>
     214sh ./updateindexes.sh <emphasis>base_root_password</emphasis>
     215</programlisting>
     216            where <emphasis>base_root_password</emphasis> is the
     217            password for the root user account within the BASE
     218            application.
     219          </para>
     220        </listitem>
     221      </varlistentry>
     222
     223      <varlistentry>
     224        <term>Remove tomcat cache</term>
     225        <listitem>
     226          <para>
     227            As tomcat user, remove cached files and directories. Do
     228            something like
     229            <programlisting>
     230cd /usr/share/apache-tomcat-5.5.15/
     231rm -rf work/Catalina
     232</programlisting>
     233          </para>
     234        </listitem>
     235      </varlistentry>
     236
     237      <varlistentry>
     238        <term>Start tomcat</term>
     239        <listitem>
     240          <para>
     241            Start the tomcat server: <command>sudo
     242              /etc/init.d/tomcat5.5 start</command>
     243          </para>
     244        </listitem>
     245      </varlistentry>
     246
     247    </variablelist>
     248
     249    <para>
     250      Done! Upgrade of BASE is finished.
     251    </para>
     252
     253  </sect1>      <!-- Upgrade instructions -->
     254
     255
     256
     257
     258  <sect1 id="installation_upgrade.installation">
     259    <title>Installation instructions</title>
     260
     261    <variablelist>
     262      <varlistentry>
     263        <term>Set up SQL database</term>
     264        <listitem>
     265          <para>
     266            BASE 2
     267            utilize <ulink
     268            url="http://www.hibernate.org/">Hibernate</ulink> for
     269            object persistence to a relational database. Hibernate
     270            supports many database engines, but so far we only work
     271            with <ulink url="http://www.mysql.com">MySQL</ulink>
     272            and <ulink
     273            url="http://www.postgresql.org/">PostgreSQL</ulink>.
     274          </para>
     275
     276          <variablelist>
     277            <varlistentry>
     278              <term>MySQL</term>
     279              <listitem>
     280                <para>
     281                  Download and install MySQL (tested with version
     282                  5.0), available from
     283                  <ulink
     284                  url="http://www.mysql.com/">http://www.mysql.com/</ulink>. You
     285                  need to be able to connect to the server over TCP,
     286                  so the <emphasis>skip-networking</emphasis> option
     287                  must <command>not</command> be used. The InnoDB
     288                  table engine is also needed, so don't disable them
     289                  (not that you would) but you may want to tune the
     290                  InnoDB behaviour before creating BASE
     291                  databases. BASE comes pre-configured for MySQL so
     292                  there is no need to change database settings in the
     293                  BASE configuration files.
     294                </para>
     295              </listitem>
     296            </varlistentry>
     297            <varlistentry>
     298              <term>PostgreSQL</term>
     299              <listitem>
     300                <para>
     301                  PostgreSQL 8.0 seems to be working very well with
     302                  BASE and Hibernate. Download and install PostgreSQL,
     303                  avaialble
     304                  from <ulink
     305                  url="http://www.postgresql.org/">http://www.postgresql.org/</ulink>. you
     306                  must edit
     307                  your <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
     308                  file. Uncomment the settings for Postgres and
     309                  comment out the settings for MySQL.
     310                </para>
     311              </listitem>
     312            </varlistentry>
     313          </variablelist>
     314
     315        </listitem>
     316      </varlistentry>
     317
     318      <varlistentry>
     319        <term>Java</term>
     320        <listitem>
     321          <para>
     322            Download and install Java SDK 1.5, available
     323            from <ulink
     324            url="http://java.sun.com/">http://java.sun.com/</ulink>. Make
     325            sure that you download the JDK version
     326            (<emphasis>not</emphasis> the JRE version). <command>Java
     327            6 is currently not supported</command>.
     328          </para>
     329        </listitem>
     330      </varlistentry>
     331
     332      <varlistentry>
     333        <term>BASE (download and unpacking)</term>
     334        <listitem>
     335          <para>
     336            <ulink
     337            url="http://base.thep.lu.se/wiki/DownloadPage">Download
     338            BASE</ulink> and unpack the downloaded file,
     339            i.e. <command>tar zxpf base-...tar.gz</command>. If you
     340            prefer to have the bleeding edge version of BASE, perform
     341            a checkout of the source from the subversion repository
     342            (subversion checkout instructions at
     343            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
     344            trac site</ulink>).
     345          </para>
     346          <para>
     347            If you choose to download the binary package, skip to the
     348            next item. The rest of us, read on and compile BASE 2. If
     349            you downloaded a source distribution, unpack the
     350            downloaded file <command>tar zxpf
     351            base-...src.tar.gz</command>, or you may have performed a
     352            subversion checkout.  Change to the 'root' base2
     353            directory, and issue <command>ant
     354            package.bin</command>. This will create a binary package
     355            in the base2 'root' directory. Unpack this new package
     356            (outside of the source file hierarchy), and from now on
     357            the instructions are the same irrespective where you got
     358            the binary package.
     359          </para>
     360          <para>
     361            <emphasis>This section is intended for advanced users and
     362              programmers only. In cases when you want to change the
     363              BASE code and try out personalized features it may be
     364              advantageous to run the tweaked BASE server against the
     365              development tree. Instructions on how to accomplish this
     366              is available in the
     367              <ulink
     368              url="http://base.thep.lu.se/chrome/site/doc/development/build.html">building
     369              BASE document</ulink>. When you return back after
     370              compiling in the subversion tree you can follow the
     371              instruction here (with obvious changes to
     372              paths).</emphasis>
     373          </para>
     374        </listitem>
     375      </varlistentry>
     376
     377      <varlistentry>
     378        <term>BASE (database engine)</term>
     379        <listitem>
     380          <para>
     381            Instructions for MySQL and PostgreSQL are available
     382            below. The database names, the <emphasis>user</emphasis>,
     383            and the <emphasis>password</emphasis> can be changed
     384            during the creation of the databases. It is recommended to
     385            change the <emphasis>password</emphasis>, the other
     386            changes can be made if required. The database names,
     387            the <emphasis>user</emphasis>, and
     388            the <emphasis>password</emphasis> are needed in a later
     389            step below when configuring BASE.
     390          </para>
     391          <variablelist>
     392            <varlistentry>
     393              <term>MySQL</term>
     394              <listitem>
     395                <para>
     396                  Create a new database for BASE, and add a
     397                  <emphasis>user</emphasis> with at least
     398                  <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
     399                  <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
     400                  <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
     401                  <emphasis>INDEX</emphasis>,
     402                  and <emphasis>ALTER</emphasis> permission for the
     403                  new database. To do this, connect to your MySQL
     404                  server and issue the next lines:
     405                  <programlisting>
     406CREATE DATABASE base2;
     407CREATE DATABASE base2dynamic;
     408GRANT ALL ON base2.* TO base2user@localhost IDENTIFIED BY 'password';
     409GRANT ALL ON base2dynamic.* TO base2user@localhost;
     410</programlisting>
     411                </para>
     412                <para>
     413                  The <filename>/path/to/base/misc/sql/createdb.mysql.sql</filename>
     414                  file contains the above statements and can be used
     415                  by the <filename>mysql</filename> command-line tool
     416                  (remember to edit
     417                  the <emphasis>user</emphasis>, <emphasis>password</emphasis>,
     418                  and the database names in the script file before
     419                  executing the command): <command>mysql -uroot -p
     420                  &lt; ./misc/sql/createdb.mysql.sql</command>. The
     421                  header in the script file contains further
     422                  information about the script.
     423                </para>
     424              </listitem>
     425            </varlistentry>
     426            <varlistentry>
     427              <term>PostgreSQL</term>
     428              <listitem>
     429                <para>
     430                  Create a new database for BASE, and add a
     431                  <emphasis>user</emphasis> with the proper
     432                  privileges. To do this, log in as your PostgreSQL
     433                  user and issue these lines (omit comments):
     434                  <programlisting>
     435createuser base2user -P
     436  # this will prompt for an password for the new user, and issue two
     437  # more question that should be answered with character 'n' for no.
     438createdb --owner base2user --encoding UNICODE base2
     439psql base2
     440  # this will start the psql command line tool. Issue the next line
     441  # within the tool and quit with a '\q'.
     442CREATE SCHEMA "dynamic" AUTHORIZATION "base2user";
     443</programlisting>
     444                  The <filename>/path/to/base/misc/sql/createdb.postgresql.sql</filename>
     445                  file contains the above statements and can be used
     446                  by the <filename>psql</filename> command-line tool:
     447                  <command>psql -f ./misc/sql/createdb.posgres.sql
     448                    template1</command> The header in the script file
     449                  contains further information about the script.
     450                </para>
     451              </listitem>
     452            </varlistentry>
     453          </variablelist>
     454        </listitem>
     455      </varlistentry>
     456
     457      <varlistentry>
     458        <term>BASE (file storage setup)</term>
     459        <listitem>
     460          <para>
     461            An area for file storage must be setup. Create an empty
     462            directory in a proper location in your file system, and
     463            set the owner to be the same as the one that the tomcat
     464            server will be running as. Remember this location for
     465            later use.
     466          </para>
     467        </listitem>
     468      </varlistentry>
     469
     470      <varlistentry>
     471        <term>BASE (configuration)</term>
     472        <listitem>
     473          <para>
     474          </para>
     475        </listitem>
     476      </varlistentry>
     477
     478      <varlistentry>
     479        <term></term>
     480        <listitem>
     481          <para>
     482          </para>
     483        </listitem>
     484      </varlistentry>
     485    </variablelist>
     486
     487
     488  </sect1>      <!-- Installation instructions -->
     489
     490
     491  <sect1 id="installation_upgrade.migration">
     492    <title>Migration instructions</title>
     493    <para></para>
     494  </sect1>      <!-- Migration instructions -->
    262495
    263496</chapter>
Note: See TracChangeset for help on using the changeset viewer.