source: trunk/doc/installation.html @ 3025

Last change on this file since 3025 was 3025, checked in by Jari Häkkinen, 15 years ago

Changed src install instructions to use 'ant package.bin'

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Date
File size: 20.1 KB
1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" "">
4    $Id: installation.html 3025 2006-12-12 13:30:59Z jari $
6    Copyright (C) 2005-2006 Jari Häkkinen, Nicklas Nordborg, Gregory Vincic
8    This file is part of BASE - BioArray Software Environment.
9    Available at
11    BASE is free software; you can redistribute it and/or modify it
12    under the terms of the GNU General Public License as published by
13    the Free Software Foundation; either version 2 of the License, or
14    (at your option) any later version.
16    BASE is distributed in the hope that it will be useful, but
17    WITHOUT ANY WARRANTY; without even the implied warranty of
19    General Public License for more details.
21    You should have received a copy of the GNU General Public License
22    along with this program; if not, write to the Free Software
23    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
24    02111-1307, USA.
30<title>BASE 2 installation instructions</title>
31<link rel=stylesheet type="text/css" href="styles.css">
35<div class="navigation">
36  <a href="index.html">BASE</a>
37  <img src="next.gif">
38  Installation instructions
41<h1>BASE 2 installation instructions</h1>
43<div class="abstract">
45  <ul>
46  <li> <a href=#installation>First time installation instructions</a>
47    for BASE 2 with comments on how to install
48    from a pristine subversion copy. </li>
49  <li> Information on <a href=#upgrade>how to upgrade</a> an existing
50    BASE 2 installation. </li>
51  <li> Information on how to perform <a href=#migration>migration of a
52    BASE 1.2</a> installation to BASE 2. </li>
53  </ul>
55  <p> Please communicate comments and suggestions regarding these
56  instructions through the BASE 2 <a
57  href=>feedback channels</a>. </p>
59  <p class="authors">
60  <b>Created by:</b> Nicklas, Jari<br>
61  <b>Last updated:</b> $Date: 2006-12-12 13:30:59 +0000 (Tue, 12 Dec 2006) $<br>
62  <b>Copyright &copy;</b> 2005-2006 The respective authors. All rights reserved.
63  </p>
67<h2><a name=installation>First time BASE 2 server installation</a></h2>
69<ol type=i>
71  <li>
72  <p>
73    <i>SQL database</i> <br>
74    Hibernate does support a plethora of database engines, but so far
75    we only work with MySQL and PostgreSQL:
76  </p>
77  <p>
78    a) MySQL<br>
79    Download and install MySQL (tested with version 5.0), available from
80    <a href=></a>. You need to
81    be able to connect to the server over TCP, so the <font
82    color=#00cc00>skip-networking</font> option must
83    <strong>not</strong> be used. The InnoDB table engine is also
84    needed, so don't disable them (not that you would) but you may
85    want to tune the InnoDB behaviour before creating BASE
86    databases. BASE comes
87    pre-configured for MySQL so there is no need to change database
88    settings in the BASE configuration files.
89  </p>
90  <p>
91    b) PostgreSQL<br>
92    PostgreSQL 8.0 seems to be working very well. Actually sometimes even better
93    than with MySQL. If you want to use Postgres instead of MySQL you will have to edit
94    your <code>base.config</code> file. Uncomment the settings for Postgres and comment
95    out the settings for MySQL.
96  </li>
98  <li>
99  <p> 
100    <i>Java</i> <br>
101    Download and install Java SDK 1.5, available
102    from <a href=""></a>. Make
103    sure that you download the JDK version (<i>not</i> the JRE
104    version).
105  </p>
106  </li>
108  <li>
109  <p> 
110    <i>BASE</i> (download and unpacking)<br>
111    <a
112    href="">Download
113    BASE</a> and unpack the downloaded file, i.e. <tt>tar zxpf
114    base-...tar.gz</tt>. If you prefer to have the bleeding edge
115    version of BASE, perform a checkout of the source from the
116    subversion repository (subversion checkout instructions at <a
117    href=>BASE trac site</a>).
118  </p>
120  <p>
121  If you choose to download the binary package, skip to the next
122  item. The rest of us, read on and compile BASE 2. If you
123  downloaded a source distribution, unpack the downloaded file <tt>tar zxpf
124  base-...src.tar.gz</tt>, or you may have performed a subversion checkout.
125  Change to the 'root' base2 directory, and issue <tt>ant
126  package.bin</tt>. This will create a binary package in the base2 root
127  directory. Unpack this new package (outside of the source file
128  hierarchy), and from now on the instructions are the same however
129  you got the binary.
130  </p>
132  <p>
133    <i>This section is intended for advanced users and programmers
134    only. In cases when you want to change the BASE code and try out
135    personalized features it may be advantageous to run the tweaked
136    BASE server against the development tree. Instructions on how to
137    accomplish this is available in the
138    <a href=development/index.html#running>developer documentation
139    pages</a>. The rest of the instructions here apply also for this
140    use case.</i>
141  </p>
142  </li>
144  <li>
145  <p> 
146    <i>BASE</i> (SQL database)<br>
147    Instructions for MySQL and PostgreSQL are available below. The
148    database names, the <tt>user</tt>, and the <tt>password</tt> can be
149    changed during the creation of the databases. It is recommended to
150    change the <tt>password</tt>, the other changes can be made if
151    required.
152  </p>
153  <p>
154    The database names, the <tt>user</tt>, and the <tt>password</tt>
155    are needed in a later step below when configuring BASE.
156  </p>
157  <p>
158    a) MySQL<br>
159    Create a new database for BASE, and add a
160    <tt>user</tt> with at least <tt>SELECT</tt>, <tt>INSERT</tt>,
161    <tt>UPDATE</tt>, <tt>DELETE</tt>, <tt>CREATE</tt>, <tt>DROP</tt>,
162    <tt>INDEX</tt> and <tt>ALTER</tt> permission for the new
163    database. To do this, connect to your MySQL server and issue the
164    next lines:
165<pre class="code">
167  CREATE DATABASE base2dynamic;
168  GRANT ALL ON base2.* TO base2user@localhost IDENTIFIED BY 'password';
169  GRANT ALL ON base2dynamic.* TO base2user@localhost;
171  </p>
173  <p>
174    The <code>base-2.0/misc/sql/createdb.mysql.sql</code> file
175    contains the above statements and can be used by the <code>mysql</code>
176    command-line tool (remember to edit the <tt>user</tt>,
177    <tt>password</tt>, and the database names in the script file before
178    executing the command):
179<pre class="code">
180mysql -uroot -p &lt; ./misc/sql/createdb.mysql.sql
182    The header in the script file contains further information about
183    the script.
184  </p>
186  <p>
187    b) PostgreSQL<br>
188    Create a new database for BASE, and add a
189    <tt>user</tt> with the proper privileges. To do this, log in as
190    your PostgreSQL user and issue the next lines:
191<pre class="code">
192  createuser base2user -P
193    # this will prompt for an password for the new user, and issue two
194    # more question that should be answered with character 'n' for no.
195  createdb --owner base2user --encoding UNICODE base2
196  psql base2
197    # this will start the psql command line tool. Issue the next line
198    # within the tool and quit with a '\q'.
199  CREATE SCHEMA "dynamic" AUTHORIZATION "base2user";
201  </p>
202  <p>
203    The <code>base-2.0/misc/sql/createdb.postgresql.sql</code> file
204    contains the above statements and can be used by the <code>psql</code>
205    command-line tool:
206<pre class="code">
207psql -f ./misc/sql/createdb.posgres.sql template1
209    The header in the script file contains further information about
210    the script.
211  </p>
212  </li>
214  <li>
215  <p> 
216    <i>BASE</i> (file storage setup)<br>
217    An area for file storage must be setup. Create an empty directory
218    in a proper location in your file system, and set the owner to be
219    the same as the one that tomcat server is running as. Remember
220    this location for later use.
221  </p>
222  </li>
224  <li>
225    <i>BASE</i> (configuration)
226    <ul>
227      <li>
228        Configure BASE, in
229        <code>base-2.0/www/WEB-INF/classes/base.config</code> do:
230        <ol type=a>
231          <li> 
232            Uncomment the database engine section that match your setup.
233          </li>
234          <li>
235            Modify the <code>db.url</code>,
236            <code>db.dynamic.catalog</code>, <code>db.username</code>,
237            and <code>db.password</code> settings to match your choice
238            in step iv) above.
239          </li>
240          <li> 
241            Modify the <code>userfiles</code> setting to match your choice
242            in step v) above.
243          </li>
244        </ol>
245      </li>
246      <li>
247        Modify extended properties as needed through
248        file <code>base-2.0/www/WEB-INF/classes/extended-properties.xml</code>. This
249        is not strictly needed but may be preferred. There is a
250        administrator <a href=admin/extended-properties.html>document
251        discussing extended properties</a> available.
252      </li>
253    </ul>
254  </li>
256  <li>
257  <p>
258    <i>BASE</i> (database initialization)<br>
259    Change directory to
260    <code>base-2.0/bin</code> and run <code></code> as
262    ./ password
264    Note, the <font color=#00cccc><i>password</i></font> you use here
265    is given to the BASE 2 web application user <i>root</i>. If the
266    initialisation script fail, it is most probably a mysql related
267    problem. Make sure mysql accept network connection, and make sure
268    your <i>base2user</i> has the proper credentials (a <tt>flush
269    privileges;</tt> in mysql might help).
270  </p>
271  </li>
273  <li>
274  <p> 
275  <i>Tomcat</i> <br>
276    Download and install tomcat 5.5.15 or later,
277    available from <a
278    href=></a>.
279    We are now recommending everyone to run a late 5.5 release since
280    the trick described in <a
281    href=>doc/tomcat_with_java_1.5.txt</a> is not needed anymore.
282    [<i>We have previously tested BASE with tomcat releases 5.0.30 and
283    5.5.7. However, these versions use a built in Java 1.4 compiler,
284    to make it work with Java 1.5 read and follow the instructions in
285    <a 
286    href=>doc/tomcat_with_java_1.5.txt</a>
287    and, consequently, download Apache ANT from <a
288    href=></a>.</i>]
289  </p>
290  </li>
293  </p>
295  <p>
296    You MUST also make sure that Tomcat uses the SERVER mode of the Java
297    run time engine (see <a href="">ticket #99</a>).
298    On Linux you do this by setting the environment variable:
299    <code>CATALINA_OPTS</code> to <code>-server</code>. It is also a good idea
300    to specify the maximum allowed memory to use: <code>-server -Xmx500m</code>
301    sets it to 500 megabytes. Basically add the next line close to the
302    top of the <code></code> script that comes with tomcat
303    (directory <code>bin</code>):
305    CATALINA_OPTS="-server -Xmx500m"
307  </p>
309  <p>
310  For more information about Tomcat options see
311  <a
312  href=""></a>.
313  </p>
315  <li>
316  <p> 
317    <i>BASE/tomcat</i> <br> 
318    Either move the
319    <code>base-2.0/www</code> directory to the tomcat webapps
320    directory or create a symbolic link from the tomcat webapps
321    directory to the <code>www</code> directory (<code>ln -s /path/to/base2/www
322    base2</code>). Start/restart tomcat, and try http://hostname/base2
323    (replace base2 with whatever you use in your tomcat webapps
324    directory) in your favourite browser, you should expect to see the
325    BASE login page after a few seconds.
326  </p>
328  <p> 
329    In some cases when redoing the installation, the behaviour of
330    tomcat/apache/base may seem strange. This may be due to tomcat's
331    caching of the applications installed. The easiest way to test
332    whether the caching creates problems is to simply delete the cached
333    files. On SuSE 9.3 this is done by (with tomcat5)
334  </p>
336<pre class="code">
337  rm -rf /etc/tomcat5/base/Catalina/localhost
338  rm -rf ~tomcat/work/Catalina
341  </li>
343  <li>
344  <p> 
345    <i>BASE, apache and apache/tomcat connector</i> 
346    <br> This step is optional. If you want run the tomcat server
347    through the apache web server, you need to install the apache
348    version 2 web server, available from <a
349    href=""></a>, and a
350    apache-tomcat connector, available from <a
351    href=""></a>.
352    So, we got you there;-) To be honest, this item is not really well
353    documented yet since we use SuSE 9.3 on our demo/test server, and
354    apache/tomcat/mod_jk comes pre-installed. What you need to do is:
355    <ol type=a>
356      <li> Get that tomcat server running in stand-alone mode. </li>
357      <li> Get the apache 2 server running. </li>
358      <li> Install mod_jk. Note, different version are used for apache
359      1.3 and 2. In SuSE 9.3 this step is done by installing
360        <code>mod_jk-ap20</code>. </li>
361      <li> Create a <code></code> file in the tomcat
362        <code>base</code> directory (commonly copied from a template). </li>
363      <li> Create a <code>jk.conf</code> file in the apache <code>conf</code>
364        directory (commonly copied from a template), and make sure that
365        <i>jk</i> is added to the modules to be loaded when apache
366        starts. </li>
367      <li> In <code>jk.conf</code> add the lines below and change paths
368        appropriately.
369<pre class="code">
370  # The following lines makes apache aware of the location of
371  # the /base2 context
372  Alias /base2 "/srv/www/tomcat5/base/webapps/base2"
373  &lt;Directory "/srv/www/tomcat5/base/webapps/base2"&gt;
374    Options Indexes FollowSymLinks
375    allow from all
376  &lt;/Directory&gt;
377  # The following lines mounts all base2 jsp files to tomcat
378  JkMount /base2 ajp13
379  JkMount /base2/* ajp13
380  # The following lines prohibits users from directly accessing WEB-INF
381  &lt;Location "/base2/WEB-INF/"&gt;
382    AllowOverride None
383    deny from all
384  &lt;/Location&gt;
386    </li>
387  </ol>
388  You must restart the apache and the tomcat server after above steps.
389  </p>
390  </li>
392  <li>
393  <p>
394    Done! Setup of BASE is finished. Happy BASEing. Now you can log on
395    to your BASE 2 server as user <i>root</i> (use the <font
396    color=#00ccc0><i>password</i></font> from the database
397    initialization step above).
398  </p>
399  </li>
403<h2><a name=upgrade>Upgrade of running BASE 2 installation</a></h2>
406<i> Upgrading BASE to versions below 2.2 may not be safe on a PostgreSQL database due to a bug in
407Hibernate. The problem is reported to Hibernate developers. There now exists
408a workaround for this problem. Read more about it on the
409<a href="">Upgrading a Postgres database</i>
410page. Note! This bug has been fixed in the Hibernate version which is shipped with
411BASE 2.2 and above.
414<ol type=i>
416  <li>
417  <p>
418  Shut down the tomcat server, i.e. do something like <tt>sudo
419  /etc/init.d/tomcat5.5 stop</tt>
420  </p>
421  </li>
423  <li>
424  <p>
425  Rename your current BASE 2 installation <tt>mv base-2.0 base-2.0_old</tt>
426  </p>
427  </li>
429  <li>
430  <p> 
431  <i>BASE</i> (download and unpacking)<br>
432  <a
433  href="">Download
434  BASE 2</a> and unpack the downloaded file, i.e. <tt>tar zxpf
435  base-...tar.gz</tt>. If you prefer to have the bleeding edge
436  version of BASE 2.0, perform a checkout of the source from the
437  subversion repository (subversion checkout instructions at <a
438  href=>BASE 2.0 trac site</a>).
439  </p>
441  <p>
442  If you choose to download the binary package, skip to the next
443  item. The rest of us, read on and compile BASE 2. If you
444  downloaded a source distribution, unpack the downloaded file <tt>tar zxpf
445  base-...src.tar.gz</tt>, or you may have performed a subversion checkout.
446  Change to the 'root' base2 directory, and issue <tt>ant
447  package.bin</tt>. This will create a binary package in the base2 root
448  directory. Unpack this new package (outside of the source file
449  hierarchy), and from now on the instructions are the same however
450  you got the binary.
451  </p>
452  </li>
454  <li>
455  <p>
456  You need to transfer settings made from the old installation
457  to the new. This is most easily done by comparing the configuration file
458  (<tt>base-2.0/www/WEB-INF/classes/base.config</tt>) between the
459  new and the old install (usually fields db.username, db.password,
460  userfiles).
461  </p>
462  <p>
463  If you are planning to remake a migration you must delete base2 and
464  base2dynamic databases, and more. You are best of performing a <a
465  href=#installation>first time installation of BASE</a> in this case.
466  </p>
467  </li>
469  <li>
470  <p>
471  <i> Note, this is not safe on a PostgreSQL database due to a bug in
472  Hibernate. The problem is reported to Hibernate developers.</i> <br>
473  It is recommended that you perform an update of your database.
474  Running the update scripts are not always necessary, but the update
475  is safe to perform even in cases when it is not needed. Change
476  directory to <tt>/path/to/base-2.0/bin/</tt> and issue: <br>
477  <tt>sh ./ <font color=#00ccc0><i>password</i></font> ;
478  sh ./ <font
479  color=#00ccc0><i>password</i></font></tt> <br> where <font
480  color=#00ccc0><i>password</i></font> is the password for the root
481  user account in the BASE application.
482  </p>
483  </li>
485  <li>
486  <p>
487  As tomcat user, remove cached files and directories. Something like this
489cd /usr/share/apache-tomcat-5.5.15/
490rm -rf work/Catalina
492  </p>
493  </li>
495  <li>
496  <p>
497  Start the tomcat server: <tt>sudo /etc/init.d/tomcat5.5 start</tt>
498  </p>
499  </li>
501  <li>
502  <p>
503    Done! Upgrade of BASE is finished.
504  </p>
505  </li>
509<h2><a name=migration>BASE 1.2 to 2.0 data migration instructions</a></h2>
512<i> Disclaimer </i> <br> We have made extensive testing of the
513migration from BASE1.2 to BASE2. To our knowledge the migration works
514but we cannot guarantee perfect functionality. The migration tool is
515supplied as is and usage is done at your risk. We are committed to
516solve migration problems at the level of transferring data from BASE
5171.2 to 2.0.x, but cannot resolve data loss issues due to imperfect
518migration in a running BASE 2.0.x server. When you start the migration
519tool you are required to pass parameter "disclaimer_understood" to the script. Remember to check that the migration
521performed well before you decide to delete your 1.2 installation.
525  Verify that your BASE 2.0 installation is up and running before
526  attempting migration. Preferably try to login using the root user
527  through the web interface.
531  Make sure your BASE 1.2 runs with the latest (<b>pristine</b>) schema
532  version. The migration will only support an unmodified BASE 1.2
533  installation. If you have an out of date schema version, please
534  upgrade to the latest schema using BASE 1.2 tools before
535  migrating. If you have made local changes to the BASE 1.2 schema you
536  need to patch the BASE 2 schema as well as change the migration
537  program.
541  There is currently no way to restart a migration. The behaviour of
542  migration is controlled through <code></code>,
543  but you should know what you do when you change parameters in this
544  file.
548Migration is performed with the following steps:
549<ol type=i>
551  <li>
552    To transfer files from BASE 1.2 (default migration behaviour), you
553    must have file system access to BASE 1.2 files,
554    i.e. the <code>/path/...base.../data</code> directory containing
555    directories <code>rawdata</code>, <code>uploads</code>,
556    <code>proocols</code>, ...
557  </li>
559  <li>
560  <p>
561  Change settings in the file
562  <code>base-2.0/dist/www/WEB-INF/classes/</code>.
563  The available options are commented:
564  <ol type=a>
565    <li>
566      Modify <code>db1.*</code> parameters to match your BASE 1.2
567      installation.
568    </li>
569    <li>
570      Set <code>userfiles</code> (note, this is not the same parameter
571      as in <code>base.config</code>) to point to the directory
572      containing the BASE 1 files (defined in a previous step above).
573    </li>
574    <li>
575      Set the <code>pluginDir</code> to point to the directory
576      where your BASE 1 plug-ins are installed. The default is
577      <code>/usr/loca/base/plugins</code>.
578    </li>
579    <li>
580      Modify <code>root.password</code>.
581    </li>
582    <li>
583      Change the <code>deletefiles</code> setting wisely. If you
584      set <code>deletefiles=yes</code> all BASE 1.2 files will be
585      physically removed when copied to BASE 2. Leave this options
586      as <code>deletefiles=no</code> unless you are absolutely sure of
587      what you are doing.
588    </li>
589  </ol>
590  </li>
591  </p>
593  <li>
594  <p>
595    Run migration utility:
596<pre class="code">
597  cd base-2.0/dist/bin
598  ./
600  </p>
601  </li>
603  <li>
604  <p> Migration done! Happy BASEing. </p>
605  </li>
Note: See TracBrowser for help on using the repository browser.