source: trunk/doc/installation.html @ 2079

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

Fixes #130. The tomcat fix is not needed anymore, updated documentation.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Date
File size: 12.8 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 2079 2006-03-15 10:02:14Z 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.0RC1 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  <p> Installation instructions for the RC1 release of BASE 2.0
46  with comments on how to install from a pristine subversion
47  copy. </p>
48
49  <p> Please communicate comments and suggestions regarding these
50  instructions through the BASE 2 <a
51  href=http://lev.thep.lu.se/trac/base/newticket?component=install>issue
52  tracking system</a>. </p>
53
54  <p class="authors">
55  <b>Created by:</b> Nicklas, Jari<br>
56  <b>Last updated:</b> $Date: 2006-03-15 10:02:14 +0000 (Wed, 15 Mar 2006) $<br>
57  <b>Copyright &copy;</b> 2005-2006 The respective authors. All rights reserved.
58  </p>
59
60</div>
61
62<p>Please understand that this is not a fully tested version of BASE 2
63... Please see <a href="http://base.thep.lu.se/">the BASE 2 pages</a>
64at the BASE web site, as well as the mailing lists for more info.</p>
65
66<h2>BASE 2 server installation</h2>
67
68<ol type=i>
69
70  <li>
71  <p> 
72    <i>MySQL</i> <br> 
73    Download and install MySQL (tested with version 4.1, later may
74    work), available from
75    <a href=http://www.mysql.com/>http://www.mysql.com/</a>. You need to
76    be able to connect to the server over TCP, so the <font
77    color=#00cc00>skip-networking</font> option must
78    <strong>not</strong> be used. The InnoDB table engine is also
79    needed, so don't disable them (not that you would). Hibernate does
80    support a plethora of database engines, but so far we only work with
81    MySQL and PostgreSQL.
82  </p>
83  <p>
84    <i>PostgreSQL</i><br>
85    PostgreSQL 8.0 seems to be working very well. Actaully sometimes even better
86    than with MySQL. If you want to use Postgres instead of MySQL you will have to edit
87    your <code>base.config</code> file. Uncomment the settings for Postgres and comment
88    out the settings for MySQL.
89  </li>
90
91  <li>
92  <p> 
93    <i>Java</i> <br>
94    Download and install Java SDK 1.5, available
95    from <a href="http://java.sun.com/">http://java.sun.com/</a>. Make
96    sure that you download the JDK version (<i>not</i> the JRE
97    version).
98  </p>
99  </li>
100
101  <li>
102  <p> 
103    <i>ANT</i> <br>
104    Download and install Apache ANT, available from
105    <a href=http://ant.apache.org/>http://ant.apache.org/</a>.
106  </p>
107  </li>
108
109  <li>
110  <p> 
111    <i>BASE</i> (download and unpacking)<br>
112    <a
113    href="http://base.thep.lu.se/base2/index.html#downloads">Download
114    BASE 2</a> and unpack the downloaded file, i.e. <tt>tar zxpf
115    base-...tar.gz</tt>. If you prefer to have the bleeding edge
116    version of BASE 2.0, perform a checkout of the source from the
117    subversion repository.
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 the downloaded
123    package. Change to the 'root' base2 directory, and issue <tt>ant
124    package</tt>. This will create a binary package in the base2 root
125    directory. Unpack this new package, and from now on the
126    instructions are the same however you got the binary.
127  </p>
128
129  <p>
130    BASE can also be run directly from the development file
131    structure. More on that some other time.
132  </p>
133  </li>
134
135  <li>
136  <p> 
137    <i>BASE</i> (SQL database)<br> 
138    Create a new database for BASE, and add a
139    <tt>user</tt> with at least <tt>SELECT</tt>, <tt>INSERT</tt>,
140    <tt>UPDATE</tt>, <tt>DELETE</tt>, <tt>CREATE</tt>, <tt>DROP</tt>,
141    <tt>INDEX</tt> and <tt>ALTER</tt> permission for the new
142    database. Connect to your mysql server and do:
143<pre class="code">
144  CREATE DATABASE base2;
145  CREATE DATABASE base2dynamic;
146  GRANT ALL ON base2.* TO base2user@localhost IDENTIFIED BY 'password';
147  GRANT ALL ON base2dynamic.* TO base2user@localhost;
148</pre>
149  </p>
150 
151  <p>
152    The <code>base-2.0RC1/misc/sql/createdb.mysql.sql</code> file
153    contains the above statments and can be used by the <code>mysql</code>
154    command-line tool:
155  </p>
156<pre class="code">
157mysql -uroot -p &lt; ./misc/sql/createdb.mysql.sql
158</pre>
159 
160  <p>
161    The database names and the <tt>user</tt> and <tt>password</tt> is
162    needed when configuring BASE below.
163  </p>
164  </li>
165
166  <li>
167  <p> 
168    <i>BASE</i> (file storage setup)<br>
169    An area for file storage must be setup. Create an empty directory
170    in a proper location in your filesystem, and set the owner to be
171    the same as the one that tomcat server is running as. Remember
172    this location for later use.
173  </p>
174  </li>
175
176  <li>
177  <p>
178    <i>BASE</i> (configuration)<br>
179    Configure BASE, in
180    <code>base-2.0RC1/www/WEB-INF/classes/base.config</code>:
181    <ol type=a>
182      <li> 
183        Uncomment the database engine section that match your setup.
184      </li>
185      <li>
186        Modify the <code>db.url</code>,
187        <code>db.dynamic.catalog</code>, <code>db.username</code>, and
188        <code>db.password</code> settings to match your choice in
189        step v) above.
190      </li>
191      <li> 
192        Modify the <code>userfiles</code> setting to match your choice
193        in step vi) above.
194      </li>
195    </ol>
196  </p>
197  </li>
198
199  <li>
200  <p>
201    <i>BASE</i> (database initialization)<br>
202    Change directory to
203    <code>base-2.0RC1/bin</code> and run <code>initdb.sh</code> as
204<pre>
205    ./initdb.sh password
206</pre>
207    Note, the <font color=#00cccc><i>password</i></font> you use here
208    is given to the BASE 2 web application user <i>root</i>. If the
209    initialisation script fail, it is most probably a mysql related
210    problem. Make sure mysql accept network connection, and make sure
211    your <i>base2user</i> has the proper credentials (a <tt>flush
212    privileges;</tt> in mysql might help).
213  </p>
214  </li>
215
216  <li>
217  <p> 
218    <i>Tomcat</i> <br>
219    Download and install tomcat 5.5.15 or later,
220    available from <a
221    href=http://jakarta.apache.org/tomcat/>http://jakarta.apache.org/tomcat/</a>.
222    We are now recommending everyone to run a late 5.5 release since
223    the trick described in <a
224    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.
225
226    We have previously tested BASE with tomcat releases 5.0.30 and
227    5.5.7. However, these versions use a built in Java 1.4 compiler,
228    to make it work with Java 1.5 read and follow the instructions in
229    <a 
230    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>
231  </p>
232 
233  <p>
234    You MUST also make sure that Tomcat uses the SERVER mode of the Java
235    runtime engine (see <a href="http://lev.thep.lu.se/trac/base/ticket/99">ticket #99</a>).
236    On Linux you do this by setting the environment variable:
237    <code>CATALINA_OPTS</code> to <code>-server</code>. It is also a good idea
238    to specify the maximum allowed memory to use: <code>-server -Xmx500m</code>
239    sets it to 500 megabytes. Basically add the next line close to the
240    top of the <code>catalina.sh</code> script that comes with tomcat
241    (diectory <code>bin</code>):
242<pre>
243    CATALINA_OPTS="-server -Xmx500m"
244</pre>
245  </p>
246 
247  <p>
248  For more information about Tomcat options see
249  <a
250  href="http://www.chemaxon.com/jchem/doc/admin/tomcat.html">http://www.chemaxon.com/jchem/doc/admin/tomcat.html</a>.
251  </p>
252
253  <li>
254  <p> 
255    <i>BASE/tomcat</i> <br> 
256    Either move the
257    <code>base-2.0RC1/www</code> directory to the tomcat webapps
258    directory or create a symbolic link from the tomcat webapps
259    directory to the <code>www</code> directory (<code>ln -s /path/to/base2/www
260    base2</code>). Start/restart tomcat, and try http://hostname/base2
261    (replace base2 with whatever you use in your tomcat webapps
262    directory) in your favourite browser, you should expect to see the
263    BASE login page after a few seconds.
264  </p>
265
266  <p> 
267    In some cases when redoing the installation, the behaviour of
268    tomcat/apache/base may seem strange. This may be due to tomcat's
269    caching of the applications installed. The easiest way to test
270    whether the caching creates problems is to simply delete the cached
271    files. On SuSE 9.3 this is done by
272  </p>
273 
274<pre class="code">
275  rm -rf /etc/tomcat5/base/Catalina/localhost
276  rm -rf ~tomcat/work/Catalina
277</pre>
278
279  </li>
280
281  <li>
282  <p> 
283    <i>BASE, apache and apache/tomcat connector</i> 
284    <br> This step is optional. If you want run the tomcat server
285    through the apache web server, you need to install the apache
286    version 2 web server, available from <a
287    href="http://www.apache.org/">http://www.apache.org/</a>, and a
288    apache-tomcat connector, available from <a
289    href="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</a>.
290    So, we got you there;-) To be honest, this item is not really well
291    documented yet since we use SuSE 9.3 on our demo/test server, and
292    apache/tomcat/mod_jk comes preinstalled. What you need to do is:
293    <ol type=a>
294      <li> Get that tomcat server running in stand-alone mode. </li>
295      <li> Get the apache 2 server running. </li>
296      <li> Install mod_jk. Note, different version are used for apache
297      1.3 and 2. In SuSE 9.3 this step is done by installing
298        <code>mod_jk-ap20</code>. </li>
299      <li> Create a <code>workers.properties</code> file in the tomcat
300        <code>base</code> directory (commonly copied from a template). </li>
301      <li> Create a <code>jk.conf</code> file in the apache <code>conf</code>
302        directory (commonly copied from a template), and make sure that
303        <i>jk</i> is added to the modules to be loaded when apache
304        starts. </li>
305      <li> In <code>jk.conf</code> add the lines below and change paths
306        appropriately.
307<pre class="code">
308  # The following lines makes apache aware of the location of
309  # the /base2 context
310  Alias /base2 "/srv/www/tomcat5/base/webapps/base2"
311  &lt;Directory "/srv/www/tomcat5/base/webapps/base2"&gt;
312    Options Indexes FollowSymLinks
313    allow from all
314  &lt;/Directory&gt;
315  # The following lines mounts all base2 jsp files to tomcat
316  JkMount /base2 ajp13
317  JkMount /base2/* ajp13
318  # The following lines prohibits users from directly accessing WEB-INF
319  &lt;Location "/base2/WEB-INF/"&gt;
320    AllowOverride None
321    deny from all
322  &lt;/Location&gt;
323</pre>
324    </li>
325  </ol>
326  </p>
327  </li>
328
329  <li>
330  <p>
331    Done! Setup of BASE is finished. Happy BASEing. Now you can log on
332    to your BASE 2 server as user <i>root</i> (use the <font
333    color=#00ccc0><i>password</i></font> from the database
334    initialization step above).
335  </p>
336  </li>
337
338</ol>
339
340<h2>BASE 1 to 2 data migration instructions</h2>
341
342<p> 
343  Verify that your BASE 2 installation is up and running before
344  attempting migration. Preferably try to login using the root user
345  through the web interface.
346</p>
347
348<p> 
349  There is currently no way to restart a migration. The behaviour of
350  migration is controlled through <code>migration.properties</code>,
351  but you should know what you do when you change parameters in this
352  file.
353</p>
354
355<p>
356Migration is performed with the following steps:
357<ol type=i>
358
359  <li>
360    To transfer files from BASE 1 (default migration behaviour), you
361    must have filesystem access to BASE 1 files,
362    i.e. the <code>/path/...base.../data</code> directory containing
363    directories <code>rawdata</code>, <code>uploads</code>,
364    <code>proocols</code>, ...
365  </li>
366
367  <li>
368  <p>
369  Change settings in the file
370  <code>base-2.0RC1/dist/www/WEB-INF/classes/migrate.properties</code>.
371  The available options are commented:
372  <ol type=a>
373    <li>
374      Modify <code>db1.*</code> parameters to match your BASE 1
375      installation.
376    </li>
377    <li>
378      Set <code>userfiles</code> (note, this is not the same parameter
379      as in <code>base.config</code>) to point to the directory
380      containing the BASE 1 files (defined in a previous step above).
381    </li>
382    <li>
383      Modify <code>root.password</code>.
384    </li>
385    <li>
386      Change the <code>deletefiles</code> setting wisely. If you
387      set <code>deletefiles=yes</code> all BASE 1 files will be
388      physically removed when copied to BASE 2. Leave this options
389      as <code>deletefiles=no</code> unless you are absolutely sure of
390      what you are doing.
391    </li>
392  </ol>
393  </li>
394  </p>
395
396  <li>
397  <p>
398    Run migration utility:
399<pre class="code">
400  cd base-2.0RC1/dist/bin
401  ./migrate_from_1.2.sh
402</pre>
403  </p>
404  </li>
405
406  <li>
407  <p> Migration done! Happy BASEing. </p>
408  </li>
409
410</ol>
411</p>
412
413</body>
414</html>
Note: See TracBrowser for help on using the repository browser.