source: trunk/doc/installation.html @ 3056

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

Changed requirements on tomcat to 5.5.16 or later.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Date
File size: 20.1 KB
Line 
1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2
3<!--
4    $Id: installation.html 3056 2007-01-10 08:32:01Z jari $
5
6    Copyright (C) 2005-2006 Jari Häkkinen, Nicklas Nordborg, Gregory Vincic
7
8    This file is part of BASE - BioArray Software Environment.
9    Available at http://base.thep.lu.se/
10
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.
15
16    BASE is distributed in the hope that it will be useful, but
17    WITHOUT ANY WARRANTY; without even the implied warranty of
18    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
19    General Public License for more details.
20
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.
25-->
26
27<html>
28
29<head>
30<title>BASE 2 installation instructions</title>
31<link rel=stylesheet type="text/css" href="styles.css">
32</head>
33
34<body>
35<div class="navigation">
36  <a href="index.html">BASE</a>
37  <img src="next.gif">
38  Installation instructions
39</div>
40
41<h1>BASE 2 installation instructions</h1>
42
43<div class="abstract">
44
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>
54
55  <p> Please communicate comments and suggestions regarding these
56  instructions through the BASE 2 <a
57  href=http://base.thep.lu.se/#Feedback>feedback channels</a>. </p>
58
59  <p class="authors">
60  <b>Created by:</b> Nicklas, Jari<br>
61  <b>Last updated:</b> $Date: 2007-01-10 08:32:01 +0000 (Wed, 10 Jan 2007) $<br>
62  <b>Copyright &copy;</b> 2005-2006 The respective authors. All rights reserved.
63  </p>
64
65</div>
66
67<h2><a name=installation>First time BASE 2 server installation</a></h2>
68
69<ol type=i>
70
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=http://www.mysql.com/>http://www.mysql.com/</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>
97
98  <li>
99  <p> 
100    <i>Java</i> <br>
101    Download and install Java SDK 1.5, available
102    from <a href="http://java.sun.com/">http://java.sun.com/</a>. Make
103    sure that you download the JDK version (<i>not</i> the JRE
104    version).
105  </p>
106  </li>
107
108  <li>
109  <p> 
110    <i>BASE</i> (download and unpacking)<br>
111    <a
112    href="http://base.thep.lu.se/wiki/DownloadPage">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=http://base.thep.lu.se/wiki/DownloadPage>BASE trac site</a>).
118  </p>
119
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>
131
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>
143
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">
166  CREATE DATABASE base2;
167  CREATE DATABASE base2dynamic;
168  GRANT ALL ON base2.* TO base2user@localhost IDENTIFIED BY 'password';
169  GRANT ALL ON base2dynamic.* TO base2user@localhost;
170</pre>
171  </p>
172 
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
181</pre>
182    The header in the script file contains further information about
183    the script.
184  </p>
185 
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";
200</pre>
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
208</pre>
209    The header in the script file contains further information about
210    the script.
211  </p>
212  </li>
213
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>
223
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>
255
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>initdb.sh</code> as
261<pre>
262    ./initdb.sh password
263</pre>
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>
272
273  <li>
274  <p> 
275  <i>Tomcat</i> <br>
276    Download and install tomcat 5.5.16 or later,
277    available from <a
278    href=http://jakarta.apache.org/tomcat/>http://jakarta.apache.org/tomcat/</a>.
279    We are now recommending everyone to run a late 5.5 release since
280    the trick described in <a
281    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.
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=http://lev.thep.lu.se/trac/base/browser/trunk/doc/tomcat_with_java_1.5.txt>doc/tomcat_with_java_1.5.txt</a>
287    and, consequently, download Apache ANT from <a
288    href=http://ant.apache.org/>http://ant.apache.org/</a>.</i>]
289  </p>
290  </li>
291
292
293  </p>
294 
295  <p>
296    You MUST also make sure that Tomcat uses the SERVER mode of the Java
297    run time engine (see <a href="http://lev.thep.lu.se/trac/base/ticket/99">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>catalina.sh</code> script that comes with tomcat
303    (directory <code>bin</code>):
304<pre>
305    CATALINA_OPTS="-server -Xmx500m"
306</pre>
307  </p>
308 
309  <p>
310  For more information about Tomcat options see
311  <a
312  href="http://www.chemaxon.com/jchem/doc/admin/tomcat.html">http://www.chemaxon.com/jchem/doc/admin/tomcat.html</a>.
313  </p>
314
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>
327
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>
335 
336<pre class="code">
337  rm -rf /etc/tomcat5/base/Catalina/localhost
338  rm -rf ~tomcat/work/Catalina
339</pre>
340
341  </li>
342
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="http://www.apache.org/">http://www.apache.org/</a>, and a
350    apache-tomcat connector, available from <a
351    href="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</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>workers.properties</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;
385</pre>
386    </li>
387  </ol>
388  You must restart the apache and the tomcat server after above steps.
389  </p>
390  </li>
391
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>
400
401</ol>
402
403<h2><a name=upgrade>Upgrade of running BASE 2 installation</a></h2>
404
405<p>
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="http://base.thep.lu.se/wiki/UpgradePostgres">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.
412</p>
413
414<ol type=i>
415
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>
422
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>
428 
429  <li>
430  <p> 
431  <i>BASE</i> (download and unpacking)<br>
432  <a
433  href="http://base.thep.lu.se/base2/index.html#downloads">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=http://lev.thep.lu.se/trac/base/wiki>BASE 2.0 trac site</a>).
439  </p>
440
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>
453
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>
468
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 ./updatedb.sh <font color=#00ccc0><i>password</i></font> ;
478  sh ./updateindexes.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>
484 
485  <li>
486  <p>
487  As tomcat user, remove cached files and directories. Something like this
488<pre>
489cd /usr/share/apache-tomcat-5.5.15/
490rm -rf work/Catalina
491</pre>
492  </p>
493  </li>
494
495  <li>
496  <p>
497  Start the tomcat server: <tt>sudo /etc/init.d/tomcat5.5 start</tt>
498  </p>
499  </li>
500
501  <li>
502  <p>
503    Done! Upgrade of BASE is finished.
504  </p>
505  </li>
506
507</ol>
508
509<h2><a name=migration>BASE 1.2 to 2.0 data migration instructions</a></h2>
510
511<p>
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
520migrate_from_1.2.sh script. Remember to check that the migration
521performed well before you decide to delete your 1.2 installation.
522</p>
523
524<p> 
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.
528</p>
529
530<p> 
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.
538</p>
539
540<p> 
541  There is currently no way to restart a migration. The behaviour of
542  migration is controlled through <code>migration.properties</code>,
543  but you should know what you do when you change parameters in this
544  file.
545</p>
546
547<p>
548Migration is performed with the following steps:
549<ol type=i>
550
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>
558
559  <li>
560  <p>
561  Change settings in the file
562  <code>base-2.0/dist/www/WEB-INF/classes/migrate.properties</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>
592
593  <li>
594  <p>
595    Run migration utility:
596<pre class="code">
597  cd base-2.0/dist/bin
598  ./migrate_from_1.2.sh
599</pre>
600  </p>
601  </li>
602
603  <li>
604  <p> Migration done! Happy BASEing. </p>
605  </li>
606
607</ol>
608</p>
609
610</body>
611</html>
Note: See TracBrowser for help on using the repository browser.