source: trunk/doc/installation.html @ 2060

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

Bumped to RC1.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Date
File size: 12.3 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 2060 2006-02-23 13:30:18Z 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-02-23 13:30:18 +0000 (Thu, 23 Feb 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.0.* or 5.5.*,
220    available from <a
221    href=http://jakarta.apache.org/tomcat/>http://jakarta.apache.org/tomcat/</a>.
222    We have tested BASE with 5.0.30 and 5.5.7, but later version should
223    also work. The versions we have tested use a built in Java 1.4
224    compiler, to make it work with Java 1.5 read and follow the
225    instructions in:
226    <code>base-2.0RC1/doc/tomcat_with_java_1.5.txt</code>.
227  </p>
228 
229  <p>
230    You MUST also make sure that Tomcat uses the SERVER mode of the Java
231    runtime engine (see <a href="http://lev.thep.lu.se/trac/base/ticket/99">ticket #99</a>).
232    On Linux you do this by setting the environment variable:
233    <code>CATALINA_OPTS</code> to <code>-server</code>. It is also a good idea
234    to specify the maximum allowed memory to use: <code>-server -Xmx500m</code>
235    sets it to 500 megabytes. For more information about Tomcat options see
236    <a href="http://www.chemaxon.com/jchem/doc/admin/tomcat.html">http://www.chemaxon.com/jchem/doc/admin/tomcat.html</a>
237  </p>
238
239  <li>
240  <p> 
241    <i>BASE/tomcat</i> <br> 
242    Either move the
243    <code>base-2.0RC1/www</code> directory to the tomcat webapps
244    directory or create a symbolic link from the tomcat webapps
245    directory to the <code>www</code> directory (<code>ln -s /path/to/base2/www
246    base2</code>). Start/restart tomcat, and try http://hostname/base2
247    (replace base2 with whatever you use in your tomcat webapps
248    directory) in your favourite browser, you should expect to see the
249    BASE login page after a few seconds.
250  </p>
251
252  <p> 
253    In some cases when redoing the installation, the behaviour of
254    tomcat/apache/base may seem strange. This may be due to tomcat's
255    caching of the applications installed. The easiest way to test
256    whether the caching creates problems is to simply delete the cached
257    files. On SuSE 9.3 this is done by
258  </p>
259 
260<pre class="code">
261  rm -rf /etc/tomcat5/base/Catalina/localhost
262  rm -rf ~tomcat/work/Catalina
263</pre>
264
265  </li>
266
267  <li>
268  <p> 
269    <i>BASE, apache and apache/tomcat connector</i> 
270    <br> This step is optional. If you want run the tomcat server
271    through the apache web server, you need to install the apache
272    version 2 web server, available from <a
273    href="http://www.apache.org/">http://www.apache.org/</a>, and a
274    apache-tomcat connector, available from <a
275    href="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</a>.
276    So, we got you there;-) To be honest, this item is not really well
277    documented yet since we use SuSE 9.3 on our demo/test server, and
278    apache/tomcat/mod_jk comes preinstalled. What you need to do is:
279    <ol type=a>
280      <li> Get that tomcat server running in stand-alone mode. </li>
281      <li> Get the apache 2 server running. </li>
282      <li> Install mod_jk. Note, different version are used for apache
283      1.3 and 2. In SuSE 9.3 this step is done by installing
284        <code>mod_jk-ap20</code>. </li>
285      <li> Create a <code>workers.properties</code> file in the tomcat
286        <code>base</code> directory (commonly copied from a template). </li>
287      <li> Create a <code>jk.conf</code> file in the apache <code>conf</code>
288        directory (commonly copied from a template), and make sure that
289        <i>jk</i> is added to the modules to be loaded when apache
290        starts. </li>
291      <li> In <code>jk.conf</code> add the lines below and change paths
292        appropriately.
293<pre class="code">
294  # The following lines makes apache aware of the location of
295  # the /base2 context
296  Alias /base2 "/srv/www/tomcat5/base/webapps/base2"
297  &lt;Directory "/srv/www/tomcat5/base/webapps/base2"&gt;
298    Options Indexes FollowSymLinks
299    allow from all
300  &lt;/Directory&gt;
301  # The following lines mounts all base2 jsp files to tomcat
302  JkMount /base2 ajp13
303  JkMount /base2/* ajp13
304  # The following lines prohibits users from directly accessing WEB-INF
305  &lt;Location "/base2/WEB-INF/"&gt;
306    AllowOverride None
307    deny from all
308  &lt;/Location&gt;
309</pre>
310    </li>
311  </ol>
312  </p>
313  </li>
314
315  <li>
316  <p>
317    Done! Setup of BASE is finished. Happy BASEing. Now you can log on
318    to your BASE 2 server as user <i>root</i> (use the <font
319    color=#00ccc0><i>password</i></font> from the database
320    initialization step above).
321  </p>
322  </li>
323
324</ol>
325
326<h2>BASE 1 to 2 data migration instructions</h2>
327
328<p> 
329  Verify that your BASE 2 installation is up and running before
330  attempting migration. Preferably try to login using the root user
331  through the web interface.
332</p>
333
334<p> 
335  There is currently no way to restart a migration. The behaviour of
336  migration is controlled through <code>migration.properties</code>,
337  but you should know what you do when you change parameters in this
338  file.
339</p>
340
341<p>
342Migration is performed with the following steps:
343<ol type=i>
344
345  <li>
346    To transfer files from BASE 1 (default migration behaviour), you
347    must have filesystem access to BASE 1 files,
348    i.e. the <code>/path/...base.../data</code> directory containing
349    directories <code>rawdata</code>, <code>uploads</code>,
350    <code>proocols</code>, ...
351  </li>
352
353  <li>
354  <p>
355  Change settings in the file
356  <code>base-2.0RC1/dist/www/WEB-INF/classes/migrate.properties</code>.
357  The available options are commented:
358  <ol type=a>
359    <li>
360      Modify <code>db1.*</code> parameters to match your BASE 1
361      installation.
362    </li>
363    <li>
364      Set <code>userfiles</code> (note, this is not the same parameter
365      as in <code>base.config</code>) to point to the directory
366      containing the BASE 1 files (defined in a previous step above).
367    </li>
368    <li>
369      Modify <code>root.password</code>.
370    </li>
371    <li>
372      Change the <code>deletefiles</code> setting wisely. If you
373      set <code>deletefiles=yes</code> all BASE 1 files will be
374      physically removed when copied to BASE 2. Leave this options
375      as <code>deletefiles=no</code> unless you are absolutely sure of
376      what you are doing.
377    </li>
378  </ol>
379  </li>
380  </p>
381
382  <li>
383  <p>
384    Run migration utility:
385<pre class="code">
386  cd base-2.0RC1/dist/bin
387  ./migrate_from_1.2.sh
388</pre>
389  </p>
390  </li>
391
392  <li>
393  <p> Migration done! Happy BASEing. </p>
394  </li>
395
396</ol>
397</p>
398
399</body>
400</html>
Note: See TracBrowser for help on using the repository browser.