source: trunk/doc/installation.html @ 3113

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

Updated installation document.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Date
File size: 19.0 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 3113 2007-02-07 01:13:41Z jari $
5
6    Copyright (C) 2005-2007 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-02-07 01:13:41 +0000 (Wed, 07 Feb 2007) $<br>
62  <b>Copyright &copy;</b> 2005-2007 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. If you want to use
93    Postgres instead of MySQL you will have to edit
94    your <code>base.config</code> file. Uncomment the settings for
95    Postgres and comment 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 downloaded
123  a source distribution, unpack the downloaded file <tt>tar zxpf
124  base-...src.tar.gz</tt>, or you may have performed a subversion
125  checkout.  Change to the 'root' base2 directory, and issue <tt>ant
126  package.bin</tt>. This will create a binary package in the base2
127  'root' directory. Unpack this new package (outside of the source
128  file hierarchy), and from now on the instructions are the same
129  irrespective where you got the binary package.
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>. When you return back after compiling in the subversion
140    tree you can follow the instruction here (with obvious changes to
141    paths).</i>
142  </p>
143  </li>
144
145  <li>
146  <p> 
147    <i>BASE</i> (SQL database)<br>
148    Instructions for MySQL and PostgreSQL are available below. The
149    database names, the <tt>user</tt>, and the <tt>password</tt> can be
150    changed during the creation of the databases. It is recommended to
151    change the <tt>password</tt>, the other changes can be made if
152    required.
153  </p>
154  <p>
155    The database names, the <tt>user</tt>, and the <tt>password</tt>
156    are needed in a later step below when configuring BASE.
157  </p>
158  <p>
159    a) MySQL<br>
160    Create a new database for BASE, and add a
161    <tt>user</tt> with at least <tt>SELECT</tt>, <tt>INSERT</tt>,
162    <tt>UPDATE</tt>, <tt>DELETE</tt>, <tt>CREATE</tt>, <tt>DROP</tt>,
163    <tt>INDEX</tt> and <tt>ALTER</tt> permission for the new
164    database. To do this, connect to your MySQL server and issue the
165    next lines:
166<pre class="code">
167  CREATE DATABASE base2;
168  CREATE DATABASE base2dynamic;
169  GRANT ALL ON base2.* TO base2user@localhost IDENTIFIED BY 'password';
170  GRANT ALL ON base2dynamic.* TO base2user@localhost;
171</pre>
172  </p>
173 
174  <p>
175    The <code>/path_to_base/misc/sql/createdb.mysql.sql</code> file
176    contains the above statements and can be used by the <code>mysql</code>
177    command-line tool (remember to edit the <tt>user</tt>,
178    <tt>password</tt>, and the database names in the script file before
179    executing the command):
180<pre class="code">
181mysql -uroot -p &lt; ./misc/sql/createdb.mysql.sql
182</pre>
183    The header in the script file contains further information about
184    the script.
185  </p>
186 
187  <p>
188    b) PostgreSQL<br>
189    Create a new database for BASE, and add a
190    <tt>user</tt> with the proper privileges. To do this, log in as
191    your PostgreSQL user and issue the next lines:
192<pre class="code">
193  createuser base2user -P
194    # this will prompt for an password for the new user, and issue two
195    # more question that should be answered with character 'n' for no.
196  createdb --owner base2user --encoding UNICODE base2
197  psql base2
198    # this will start the psql command line tool. Issue the next line
199    # within the tool and quit with a '\q'.
200  CREATE SCHEMA "dynamic" AUTHORIZATION "base2user";
201</pre>
202  </p>
203  <p>
204    The <code>/path_to_base/misc/sql/createdb.postgresql.sql</code> file
205    contains the above statements and can be used by the <code>psql</code>
206    command-line tool:
207<pre class="code">
208psql -f ./misc/sql/createdb.posgres.sql template1
209</pre>
210    The header in the script file contains further information about
211    the script.
212  </p>
213  </li>
214
215  <li>
216  <p> 
217    <i>BASE</i> (file storage setup)<br>
218    An area for file storage must be setup. Create an empty directory
219    in a proper location in your file system, and set the owner to be
220    the same as the one that tomcat server is running as. Remember
221    this location for later use.
222  </p>
223  </li>
224
225  <li>
226    <i>BASE</i> (configuration)
227    <ul>
228      <li>
229        Configure BASE, in
230        <code>/path_to_base/www/WEB-INF/classes/base.config</code> do:
231        <ol type=a>
232          <li> 
233            Uncomment the database engine section that match your setup.
234          </li>
235          <li>
236            Modify the <code>db.url</code>,
237            <code>db.dynamic.catalog</code>, <code>db.username</code>,
238            and <code>db.password</code> settings to match your choice
239            in step iv) above.
240          </li>
241          <li> 
242            Modify the <code>userfiles</code> setting to match your choice
243            in step v) above.
244          </li>
245        </ol>
246      </li>
247      <li>
248        Modify extended properties as needed through
249        file <code>/path_to_base/www/WEB-INF/classes/extended-properties.xml</code>. This
250        is not strictly needed but may be preferred. There is a
251        administrator <a href=admin/extended-properties.html>document
252        discussing extended properties</a> available.
253      </li>
254    </ul>
255  </li>
256
257  <li>
258  <p>
259    <i>BASE</i> (database initialization)<br>
260    Change directory to
261    <code>/path_to_base/bin</code> and run <code>initdb.sh</code> as
262<pre>
263    ./initdb.sh password
264</pre>
265    Note, the <font color=#00cccc><i>password</i></font> you use here
266    is given to the BASE 2 web application user <i>root</i>. If the
267    initialisation script fail, it is most probably a mysql related
268    problem. Make sure mysql accept network connection, and make sure
269    your <i>base2user</i> has the proper credentials (a <tt>flush
270    privileges;</tt> in mysql might help).
271  </p>
272  </li>
273
274  <li>
275  <p> 
276  <i>Tomcat</i> <br>
277    Download and install tomcat 5.5.16 or later,
278    available from <a
279    href=http://jakarta.apache.org/tomcat/>http://jakarta.apache.org/tomcat/</a>.
280  </p>
281  <p>
282    You MUST make sure that Tomcat uses the SERVER mode of the Java
283    run time engine (see <a href="http://lev.thep.lu.se/trac/base/ticket/99">ticket #99</a>).
284    On Linux you do this by setting the environment variable:
285    <code>CATALINA_OPTS</code> to <code>-server</code>. It is also a good idea
286    to specify the maximum allowed memory to use: <code>-server -Xmx500m</code>
287    sets it to 500 megabytes. Basically add the next line close to the
288    top of the <code>catalina.sh</code> script that comes with tomcat
289    (directory <code>bin</code>):
290<pre>
291    CATALINA_OPTS="-server -Xmx500m"
292</pre>
293  </p>
294 
295  <p>
296  For more information about Tomcat options see
297  <a
298  href="http://www.chemaxon.com/jchem/doc/admin/tomcat.html">http://www.chemaxon.com/jchem/doc/admin/tomcat.html</a>.
299  </p>
300  </li>
301  <li>
302  <p> 
303    <i>BASE/tomcat</i> <br> 
304    Either move the
305    <code>/path_to_base/www</code> directory to the tomcat webapps
306    directory or create a symbolic link from the tomcat webapps
307    directory to the <code>www</code> directory (<code>ln -s /path_to_base/www
308    base2</code>). Start/restart tomcat, and try http://hostname:8080/base2
309    (replace base2 with whatever you use in your tomcat webapps
310    directory) in your favourite browser, you should expect to see the
311    BASE login page after a few seconds.
312  </p>
313  </li>
314
315  <li>
316  <p> 
317    <i>BASE, apache and apache/tomcat connector</i> 
318    <br> <strong>This step is optional</strong>. If you want run the
319    tomcat server
320    through the apache web server, you need to install the apache
321    version 2 web server, available from <a
322    href="http://www.apache.org/">http://www.apache.org/</a>, and a
323    apache-tomcat connector, available from <a
324    href="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</a>.
325    So, we got you there;-) To be honest, this item is not really well
326    documented since we use SuSE 9.3 on our demo/test server, and
327    apache/tomcat/mod_jk comes pre-installed. What you need to do is:
328    <ol type=a>
329      <li> Get that tomcat server running in stand-alone mode. </li>
330      <li> Get the apache 2 server running. </li>
331      <li> Install mod_jk. Note, different version are used for apache
332      1.3 and 2. In SuSE 9.3 this step is done by installing
333        <code>mod_jk-ap20</code>. </li>
334      <li> Create a <code>workers.properties</code> file in the tomcat
335        <code>base</code> directory (commonly copied from a template). </li>
336      <li> Create a <code>jk.conf</code> file in the apache <code>conf</code>
337        directory (commonly copied from a template), and make sure that
338        <i>jk</i> is added to the modules to be loaded when apache
339        starts. </li>
340      <li> In <code>jk.conf</code> add the lines below and change paths
341        appropriately.
342<pre class="code">
343  # The following lines makes apache aware of the location of
344  # the /base2 context
345  Alias /base2 "/srv/www/tomcat5/base/webapps/base2"
346  &lt;Directory "/srv/www/tomcat5/base/webapps/base2"&gt;
347    Options Indexes FollowSymLinks
348    allow from all
349  &lt;/Directory&gt;
350  # The following lines mounts all base2 jsp files to tomcat
351  JkMount /base2 ajp13
352  JkMount /base2/* ajp13
353  # The following lines prohibits users from directly accessing WEB-INF
354  &lt;Location "/base2/WEB-INF/"&gt;
355    AllowOverride None
356    deny from all
357  &lt;/Location&gt;
358</pre>
359    </li>
360  </ol>
361  You must restart the apache and the tomcat server after above steps.
362  </p>
363  </li>
364
365  <li>
366  <p>
367    Done! Setup of BASE is finished. Happy BASEing. Now you can log on
368    to your BASE 2 server as user <i>root</i> (use the <font
369    color=#00ccc0><i>password</i></font> from the database
370    initialization step above).
371  </p>
372  </li>
373
374</ol>
375
376<h2><a name=upgrade>Upgrade of running BASE 2 installation</a></h2>
377
378<p>
379<i> Note to PostgreSQL users: Upgrading BASE to versions earlier than
380v2.2 is not be safe with an PostgreSQL database engine due to a bug in
381Hibernate. The problem is reported to Hibernate developers. There now
382exists a workaround for this problem. Read more about it on the
383<a href="http://base.thep.lu.se/wiki/UpgradePostgres">Upgrading a
384Postgres database</a> page. Note! The Hibernate bug has been fixed in
385the Hibernate package shipped with BASE 2.2 and above. </i>
386</p>
387
388<ol type=i>
389
390  <li>
391  <p>
392  Shut down the tomcat server, i.e. do something like <tt>sudo
393  /etc/init.d/tomcat5.5 stop</tt>
394  </p>
395  </li>
396
397  <li>
398  <p>
399  Rename your current BASE 2 installation <tt>mv /path_to_base
400  /path_to_base_old</tt>
401  </p>
402  </li>
403 
404  <li>
405  <p> 
406  <i>BASE</i> (download and unpacking)<br>
407  <a
408  href="http://base.thep.lu.se/base2/index.html#downloads">Download
409  BASE 2</a> and unpack the downloaded file, i.e. <tt>tar zxpf
410  base-...tar.gz</tt>. If you prefer to have the bleeding edge
411  version of BASE 2, perform a checkout of the source from the
412  subversion repository (subversion checkout instructions at <a
413  href=http://base.thep.lu.se>BASE 2 trac site</a>).
414  </p>
415
416  <p>
417  If you choose to download the binary package, skip to the next
418  item. The rest of us, read on and compile BASE 2. If you downloaded
419  a source distribution, unpack the downloaded file <tt>tar zxpf
420  base-...src.tar.gz</tt>, or you may have performed a subversion
421  checkout.  Change to the 'root' BASE 2 directory, and issue <tt>ant
422  package.bin</tt>. This will create a binary package in the BASE 2
423  'root' directory. Unpack this new package (outside of the source
424  file hierarchy), and from now on the instructions are the same
425  irrespective where you got the binary package.
426  </p>
427  </li>
428
429  <li>
430  <p>
431  You need to transfer settings made from the old installation to the
432  new. This is most easily done by comparing the configuration file
433  (<tt>/path_to_base/www/WEB-INF/classes/base.config</tt>) between the
434  new and the old install (usually fields db.username, db.password,
435  userfiles need to be transferred).
436  </p>
437  <p>
438  If you are planning to remake a migration you must delete base2 and
439  base2dynamic databases, and more. You are best of performing a <a
440  href=#installation>first time installation of BASE</a> in this case.
441  </p>
442  </li>
443
444  <li>
445  <p>
446  It is recommended that you also perform an update of your
447  database.  Running the update scripts are not always necessary when
448  upgrading BASE 2, but the update is safe to perform even in cases
449  when it is not needed. Change directory
450  to <tt>/path_to_base/bin/</tt> and issue: <br>
451  <tt>sh ./updatedb.sh <font color=#00ccc0><i>password</i></font> ;
452  sh ./updateindexes.sh <font
453  color=#00ccc0><i>password</i></font></tt> <br> where <font
454  color=#00ccc0><i>password</i></font> is the password for the root
455  user account in the BASE application.
456  </p>
457  </li>
458 
459  <li>
460  <p>
461  As tomcat user, remove cached files and directories. Do something
462  like this
463<pre>
464cd /usr/share/apache-tomcat-5.5.15/
465rm -rf work/Catalina
466</pre>
467  </p>
468  </li>
469
470  <li>
471  <p>
472  Start the tomcat server: <tt>sudo /etc/init.d/tomcat5.5 start</tt>
473  </p>
474  </li>
475
476  <li>
477  <p>
478    Done! Upgrade of BASE is finished.
479  </p>
480  </li>
481
482</ol>
483
484<h2><a name=migration>BASE 1.2 to 2.2 data migration instructions</a></h2>
485
486<p>
487<i> Disclaimer </i> <br> We have made extensive testing of the
488migration from BASE1.2 to BASE2. To our knowledge the migration works
489but we cannot guarantee perfect functionality. The migration tool is
490supplied as is and usage is done at your risk. We are committed to
491solve migration problems at the level of transferring data from BASE
4921.2 to 2.2.x, but cannot resolve data loss issues in a running BASE 2
493server due to imperfect migration. When you start the migration tool
494you are required to pass parameter "disclaimer_understood" to the
495migrate_from_1.2.sh script. Remember to check that the migration
496performed well before you decide to delete your 1.2 installation.
497</p>
498
499<p> 
500  Verify that your BASE 2 installation is up and running before
501  attempting migration. Preferably try to login using the root user
502  through the web interface.
503</p>
504
505<p> 
506  Make sure your BASE 1.2 runs with the latest (<b>pristine</b>) schema
507  version. The migration will only support an unmodified BASE 1.2
508  installation. If you have an out of date schema version, please
509  upgrade to the latest schema using BASE 1.2 tools before
510  migrating. If you have made local changes to the BASE 1.2 schema you
511  need to patch the BASE 2 schema as well as change the migration
512  program.
513</p>
514
515<p> 
516  There is currently no way to restart a migration. The behaviour of
517  migration is controlled through <code>migration.properties</code>,
518  but you should know what you do when you change parameters in this
519  file.
520</p>
521
522<p>
523Migration is performed with the following steps:
524<ol type=i>
525
526  <li>
527    To transfer files from BASE 1.2 (default migration behaviour), you
528    must have file system access to BASE 1.2 files,
529    i.e. the <code>/path/...base.../data</code> directory containing
530    directories <code>rawdata</code>, <code>uploads</code>,
531    <code>proocols</code>, ...
532  </li>
533
534  <li>
535  <p>
536  Change settings in the file
537  <code>/path_to_base/dist/www/WEB-INF/classes/migrate.properties</code>.
538  The available options are commented:
539  <ol type=a>
540    <li>
541      Modify <code>db1.*</code> parameters to match your BASE 1.2
542      installation.
543    </li>
544    <li>
545      Set <code>userfiles</code> (note, this is not the same parameter
546      as in <code>base.config</code>) to point to the directory
547      containing the BASE 1 files (defined in a previous step above).
548    </li>
549    <li>
550      Set the <code>pluginDir</code> to point to the directory
551      where your BASE 1 plug-ins are installed. The default is
552      <code>/usr/local/base/plugins</code>.
553    </li>
554    <li>
555      Modify <code>root.password</code>.
556    </li>
557    <li>
558      Change the <code>deletefiles</code> setting wisely. If you
559      set <code>deletefiles=yes</code> all BASE 1.2 files will be
560      physically removed when copied to BASE 2. Leave this options
561      as <code>deletefiles=no</code> unless you are absolutely sure of
562      what you are doing.
563    </li>
564  </ol>
565  </li>
566  </p>
567
568  <li>
569  <p>
570    Run migration utility:
571<pre class="code">
572  cd /path_to_base/dist/bin
573  ./migrate_from_1.2.sh
574</pre>
575  </p>
576  </li>
577
578  <li>
579  <p> Migration done! Happy BASEing. </p>
580  </li>
581
582</ol>
583</p>
584
585</body>
586</html>
Note: See TracBrowser for help on using the repository browser.