Changeset 3113

Timestamp:

Feb 7, 2007, 2:13:41 AM (17 years ago)

Author:

Jari Häkkinen

Message:

Updated installation document.

File:

• trunk/doc/installation.html (modified) (25 diffs)

trunk/doc/installation.html

@@ -4 +4 @@
     $Id$
 
-    Copyright (C) 2005-2006 Jari Häkkinen, Nicklas Nordborg, Gregory Vincic
+    Copyright (C) 2005-2007 Jari Häkkinen, Nicklas Nordborg, Gregory Vincic
 
     This file is part of BASE - BioArray Software Environment.
@@ -60 +60 @@
   <b>Created by:</b> Nicklas, Jari<br>
   <b>Last updated:</b> $Date$<br>
-  <b>Copyright &copy;</b> 2005-2006 The respective authors. All rights reserved.
+  <b>Copyright &copy;</b> 2005-2007 The respective authors. All rights reserved.
   </p>
 
@@ -90 +90 @@
   <p>
     b) PostgreSQL<br>
-    PostgreSQL 8.0 seems to be working very well. Actually sometimes even better 
-    than with MySQL. If you want to use Postgres instead of MySQL you will have to edit
-    your <code>base.config</code> file. Uncomment the settings for Postgres and comment
-    out the settings for MySQL.
+    PostgreSQL 8.0 seems to be working very well. If you want to use
+    Postgres instead of MySQL you will have to edit
+    your <code>base.config</code> file. Uncomment the settings for
+    Postgres and comment out the settings for MySQL.
   </li>
 
@@ -120 +120 @@
   <p>
   If you choose to download the binary package, skip to the next
-  item. The rest of us, read on and compile BASE 2. If you
-  downloaded a source distribution, unpack the downloaded file <tt>tar zxpf
-  base-...src.tar.gz</tt>, or you may have performed a subversion checkout.
-  Change to the 'root' base2 directory, and issue <tt>ant
-  package.bin</tt>. This will create a binary package in the base2 root
-  directory. Unpack this new package (outside of the source file
-  hierarchy), and from now on the instructions are the same however
-  you got the binary.
+  item. The rest of us, read on and compile BASE 2. If you downloaded
+  a source distribution, unpack the downloaded file <tt>tar zxpf
+  base-...src.tar.gz</tt>, or you may have performed a subversion
+  checkout.  Change to the 'root' base2 directory, and issue <tt>ant
+  package.bin</tt>. This will create a binary package in the base2
+  'root' directory. Unpack this new package (outside of the source
+  file hierarchy), and from now on the instructions are the same
+  irrespective where you got the binary package.
   </p>
 
@@ -137 +137 @@
     accomplish this is available in the
     <a href=development/index.html#running>developer documentation
-    pages</a>. The rest of the instructions here apply also for this
-    use case.</i>
+    pages</a>. When you return back after compiling in the subversion
+    tree you can follow the instruction here (with obvious changes to
+    paths).</i>
   </p>
   </li>
@@ -172 +173 @@
   
   <p>
-    The <code>base-2.0/misc/sql/createdb.mysql.sql</code> file 
+    The <code>/path_to_base/misc/sql/createdb.mysql.sql</code> file 
     contains the above statements and can be used by the <code>mysql</code>
     command-line tool (remember to edit the <tt>user</tt>,
@@ -201 +202 @@
   </p>
   <p>
-    The <code>base-2.0/misc/sql/createdb.postgresql.sql</code> file 
+    The <code>/path_to_base/misc/sql/createdb.postgresql.sql</code> file 
     contains the above statements and can be used by the <code>psql</code>
     command-line tool:
@@ -227 +228 @@
       <li>
         Configure BASE, in
-        <code>base-2.0/www/WEB-INF/classes/base.config</code> do:
+        <code>/path_to_base/www/WEB-INF/classes/base.config</code> do:
         <ol type=a>
           <li> 
@@ -246 +247 @@
       <li>
         Modify extended properties as needed through
-        file <code>base-2.0/www/WEB-INF/classes/extended-properties.xml</code>. This
+        file <code>/path_to_base/www/WEB-INF/classes/extended-properties.xml</code>. This
         is not strictly needed but may be preferred. There is a
         administrator <a href=admin/extended-properties.html>document
@@ -258 +259 @@
     <i>BASE</i> (database initialization)<br>
     Change directory to
-    <code>base-2.0/bin</code> and run <code>initdb.sh</code> as
+    <code>/path_to_base/bin</code> and run <code>initdb.sh</code> as
 <pre>
     ./initdb.sh password
@@ -277 +278 @@
     available from <a
     href=http://jakarta.apache.org/tomcat/>http://jakarta.apache.org/tomcat/</a>.
-    We are now recommending everyone to run a late 5.5 release since
-    the trick described in <a
-    href=http://lev.thep.lu.se/trac/base/browser/trunk/doc/tomcat_with_java_1.5.txt>doc/tomcat_with_java_1.5.txt</a> is not needed anymore.
-    [<i>We have previously tested BASE with tomcat releases 5.0.30 and
-    5.5.7. However, these versions use a built in Java 1.4 compiler,
-    to make it work with Java 1.5 read and follow the instructions in
-    <a 
-    href=http://lev.thep.lu.se/trac/base/browser/trunk/doc/tomcat_with_java_1.5.txt>doc/tomcat_with_java_1.5.txt</a>
-    and, consequently, download Apache ANT from <a
-    href=http://ant.apache.org/>http://ant.apache.org/</a>.</i>]
-  </p>
-  </li>
-
-
-  </p>
-  
-  <p>
-    You MUST also make sure that Tomcat uses the SERVER mode of the Java
+  </p>
+  <p>
+    You MUST make sure that Tomcat uses the SERVER mode of the Java
     run time engine (see <a href="http://lev.thep.lu.se/trac/base/ticket/99">ticket #99</a>).
     On Linux you do this by setting the environment variable:
@@ -312 +298 @@
   href="http://www.chemaxon.com/jchem/doc/admin/tomcat.html">http://www.chemaxon.com/jchem/doc/admin/tomcat.html</a>.
   </p>
-
+  </li>
   <li>
   <p> 
     <i>BASE/tomcat</i> <br> 
     Either move the
-    <code>base-2.0/www</code> directory to the tomcat webapps
+    <code>/path_to_base/www</code> directory to the tomcat webapps
     directory or create a symbolic link from the tomcat webapps
-    directory to the <code>www</code> directory (<code>ln -s /path/to/base2/www
-    base2</code>). Start/restart tomcat, and try http://hostname/base2
+    directory to the <code>www</code> directory (<code>ln -s /path_to_base/www
+    base2</code>). Start/restart tomcat, and try http://hostname:8080/base2
     (replace base2 with whatever you use in your tomcat webapps
     directory) in your favourite browser, you should expect to see the
     BASE login page after a few seconds. 
   </p>
-
-  <p> 
-    In some cases when redoing the installation, the behaviour of
-    tomcat/apache/base may seem strange. This may be due to tomcat's
-    caching of the applications installed. The easiest way to test
-    whether the caching creates problems is to simply delete the cached
-    files. On SuSE 9.3 this is done by (with tomcat5)
-  </p>
-  
-<pre class="code">
-  rm -rf /etc/tomcat5/base/Catalina/localhost
-  rm -rf ~tomcat/work/Catalina
-</pre>
-
   </li>
 
@@ -344 +316 @@
   <p> 
     <i>BASE, apache and apache/tomcat connector</i> 
-    <br> This step is optional. If you want run the tomcat server
+    <br> <strong>This step is optional</strong>. If you want run the
+    tomcat server
     through the apache web server, you need to install the apache
     version 2 web server, available from <a
@@ -351 +324 @@
     href="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</a>.
     So, we got you there;-) To be honest, this item is not really well
-    documented yet since we use SuSE 9.3 on our demo/test server, and
+    documented since we use SuSE 9.3 on our demo/test server, and
     apache/tomcat/mod_jk comes pre-installed. What you need to do is:
     <ol type=a>
@@ -404 +377 @@
 
 <p>
-<i> Upgrading BASE to versions below 2.2 may not be safe on a PostgreSQL database due to a bug in
-Hibernate. The problem is reported to Hibernate developers. There now exists
-a workaround for this problem. Read more about it on the
-<a href="http://base.thep.lu.se/wiki/UpgradePostgres">Upgrading a Postgres database</i>
-page. Note! This bug has been fixed in the Hibernate version which is shipped with 
-BASE 2.2 and above.
+<i> Note to PostgreSQL users: Upgrading BASE to versions earlier than
+v2.2 is not be safe with an PostgreSQL database engine due to a bug in
+Hibernate. The problem is reported to Hibernate developers. There now
+exists a workaround for this problem. Read more about it on the
+<a href="http://base.thep.lu.se/wiki/UpgradePostgres">Upgrading a
+Postgres database</a> page. Note! The Hibernate bug has been fixed in
+the Hibernate package shipped with BASE 2.2 and above. </i>
 </p>
 
@@ -423 +397 @@
   <li>
   <p>
-  Rename your current BASE 2 installation <tt>mv base-2.0 base-2.0_old</tt>
+  Rename your current BASE 2 installation <tt>mv /path_to_base
+  /path_to_base_old</tt>
   </p>
   </li>
@@ -434 +409 @@
   BASE 2</a> and unpack the downloaded file, i.e. <tt>tar zxpf
   base-...tar.gz</tt>. If you prefer to have the bleeding edge
-  version of BASE 2.0, perform a checkout of the source from the
+  version of BASE 2, perform a checkout of the source from the
   subversion repository (subversion checkout instructions at <a
-  href=http://lev.thep.lu.se/trac/base/wiki>BASE 2.0 trac site</a>).
+  href=http://base.thep.lu.se>BASE 2 trac site</a>).
   </p>
 
   <p>
   If you choose to download the binary package, skip to the next
-  item. The rest of us, read on and compile BASE 2. If you
-  downloaded a source distribution, unpack the downloaded file <tt>tar zxpf
-  base-...src.tar.gz</tt>, or you may have performed a subversion checkout.
-  Change to the 'root' base2 directory, and issue <tt>ant
-  package.bin</tt>. This will create a binary package in the base2 root
-  directory. Unpack this new package (outside of the source file
-  hierarchy), and from now on the instructions are the same however
-  you got the binary.
-  </p>
-  </li>
-
-  <li>
-  <p>
-  You need to transfer settings made from the old installation
-  to the new. This is most easily done by comparing the configuration file
-  (<tt>base-2.0/www/WEB-INF/classes/base.config</tt>) between the
-  new and the old install (usually fields db.username, db.password,
-  userfiles).
+  item. The rest of us, read on and compile BASE 2. If you downloaded
+  a source distribution, unpack the downloaded file <tt>tar zxpf
+  base-...src.tar.gz</tt>, or you may have performed a subversion
+  checkout.  Change to the 'root' BASE 2 directory, and issue <tt>ant
+  package.bin</tt>. This will create a binary package in the BASE 2
+  'root' directory. Unpack this new package (outside of the source
+  file hierarchy), and from now on the instructions are the same
+  irrespective where you got the binary package.
+  </p>
+  </li>
+
+  <li>
+  <p>
+  You need to transfer settings made from the old installation to the
+  new. This is most easily done by comparing the configuration file
+  (<tt>/path_to_base/www/WEB-INF/classes/base.config</tt>) between the
+  new and the old install (usually fields db.username, db.password,
+  userfiles need to be transferred).
   </p>
   <p>
@@ -469 +444 @@
   <li>
   <p>
-  <i> Note, this is not safe on a PostgreSQL database due to a bug in
-  Hibernate. The problem is reported to Hibernate developers.</i> <br>
-  It is recommended that you perform an update of your database.
-  Running the update scripts are not always necessary, but the update
-  is safe to perform even in cases when it is not needed. Change
-  directory to <tt>/path/to/base-2.0/bin/</tt> and issue: <br>
+  It is recommended that you also perform an update of your
+  database.  Running the update scripts are not always necessary when
+  upgrading BASE 2, but the update is safe to perform even in cases
+  when it is not needed. Change directory
+  to <tt>/path_to_base/bin/</tt> and issue: <br>
   <tt>sh ./updatedb.sh <font color=#00ccc0><i>password</i></font> ;
   sh ./updateindexes.sh <font
@@ -485 +459 @@
   <li>
   <p>
-  As tomcat user, remove cached files and directories. Something like this
+  As tomcat user, remove cached files and directories. Do something
+  like this
 <pre>
 cd /usr/share/apache-tomcat-5.5.15/
@@ -507 +482 @@
 </ol>
 
-<h2><a name=migration>BASE 1.2 to 2.0 data migration instructions</a></h2>
+<h2><a name=migration>BASE 1.2 to 2.2 data migration instructions</a></h2>
 
 <p>
@@ -515 +490 @@
 supplied as is and usage is done at your risk. We are committed to
 solve migration problems at the level of transferring data from BASE
-1.2 to 2.0.x, but cannot resolve data loss issues due to imperfect
-migration in a running BASE 2.0.x server. When you start the migration
-tool you are required to pass parameter "disclaimer_understood" to the
+1.2 to 2.2.x, but cannot resolve data loss issues in a running BASE 2
+server due to imperfect migration. When you start the migration tool
+you are required to pass parameter "disclaimer_understood" to the
 migrate_from_1.2.sh script. Remember to check that the migration
 performed well before you decide to delete your 1.2 installation.
@@ -523 +498 @@
 
 <p> 
-  Verify that your BASE 2.0 installation is up and running before
+  Verify that your BASE 2 installation is up and running before
   attempting migration. Preferably try to login using the root user
   through the web interface.
@@ -560 +535 @@
   <p>
   Change settings in the file
-  <code>base-2.0/dist/www/WEB-INF/classes/migrate.properties</code>.
+  <code>/path_to_base/dist/www/WEB-INF/classes/migrate.properties</code>.
   The available options are commented:
   <ol type=a>
@@ -575 +550 @@
       Set the <code>pluginDir</code> to point to the directory
       where your BASE 1 plug-ins are installed. The default is
-      <code>/usr/loca/base/plugins</code>.
+      <code>/usr/local/base/plugins</code>.
     </li>
     <li>
@@ -595 +570 @@
     Run migration utility:
 <pre class="code">
-  cd base-2.0/dist/bin
+  cd /path_to_base/dist/bin
   ./migrate_from_1.2.sh
 </pre>