Project

General

Profile

1
<!-- 
2
  *   '$RCSfile$'
3
  *     Purpose: web page describing the installation of Metacat
4
  *   Copyright: 2000 Regents of the University of California and the
5
  *               National Center for Ecological Analysis and Synthesis
6
  *     Authors: Chad Berkley
7
  *
8
  *    '$Author: jones $'
9
  *      '$Date: 2004-06-09 13:32:35 -0700 (Wed, 09 Jun 2004) $'
10
  *  '$Revision: 2183 $'
11
  *
12
  *
13
  -->
14
  
15
<!DOCTYPE html PUBLIC "-//W3C//DTD html 4.0//EN">
16
<html>
17

    
18
<head>
19
  <title>Metacat Installation Instructions</title>
20
  <link rel="stylesheet" type="text/css" href="@docrooturl@default.css">
21
</head>
22

    
23
<body>
24

    
25
<table class="tabledefault" width="100%">
26
<tr><td rowspan="2"><img src="@docrooturl@images/KNBLogo.gif"></td>
27
<td colspan="7">
28
<div class="title">Metacat UNIX Installation Instructions</div>
29
</td>
30
</tr>
31
<tr>
32
  <td><a href="@server@/" class="toollink"> KNB Home </a></td>
33
  <td><a href="@server@/data.html" class="toollink"> Data </a></td>
34
  <td><a href="@server@/people.html" class="toollink"> People </a></td>
35
  <td><a href="@server@/informatics" class="toollink"> Informatics </a></td>
36
  <td><a href="@server@/biodiversity" class="toollink"> Biocomplexity </a></td>
37
  <td><a href="@server@/education" class="toollink"> Education </a></td>
38
  <td><a href="@server@/software" class="toollink"> Software </a></td>
39
</tr>
40
</table>
41
<hr>
42

    
43
<table class="tabledefault" width="100%">
44
<td class="tablehead" colspan="2"><p class="emphasis">***Disclaimer***</p></td>
45
<tr>
46
<td>
47
  <p class="emphasis">
48
   These installation instructions are meant for a systems administrator/DBA
49
   or someone who is an advanced computer user.  They are NOT meant for
50
   the average computer user.  Please realize that by executing these
51
   instructions, you may have to trouble shoot many advanced issues yourself.
52
</td>
53
</tr>
54
</table>
55

    
56
<table class="tabledefault" width="100%">
57
<td class="tablehead" colspan="2"><p>Pre-Installation</p></td>
58
<tr>
59
<td>
60
  <p class="header">Minimum Requirements</p> 
61
  <p>
62
   Installing Metacat requires a server running an SQL92 compliant database
63
   (Oracle 8i recommended) with at least 128MB RAM, and a Pentium III class
64
   processor or higher.  The amount of disk space required depends on the
65
   size of your RDBMS tablespace (which should be at least 10 MB, 
66
   however Metacat itself requires only about 1 MB of free space after 
67
   installation.  These instructions assume a Linux environment but may
68
   work on other UNIX type environments, however this has not been tested.
69
  </p>
70
  <p class = "header">Additional Required Software</p>
71
  <p>
72
   The server on which you wish to install Metacat must have the following
73
   software installed and running correctly before attempting to install
74
   Metacat.
75
   <ul>
76
     <li><a href="http://www.oracle.com">Oracle 8i</a> (or another SQL92
77
         compliant RDBMS like Postgres)</li>
78
     <li><a href="http://jakarta.apache.org/ant/index.html">Apache Jakarta-Ant</a>
79
     </li>
80
     <li><a href="http://jakarta.apache.org/tomcat/index.html">Apache Jakarta-Tomcat</a>
81
       <p class="emphasis">Note: For a more robust web serving environment, 
82
       Apache web server should
83
       be installed along with Tomcat and the two should be integrated
84
       as described on the Apache web site.</p>
85
     </li>
86
   </ul>
87
  </p>
88
</td>
89
</tr>
90
</table>
91

    
92
<table class="tabledefault" width="100%">
93
<td class="tablehead" colspan="2"><p>Aditional Software Setup</p></td>
94
<tr>
95
<td>
96
  <p class="header">Java</p>
97
  <p>You'll need a recent Java SDK, preferably j2sdk1.4.2 or later.  We haven't 
98
  tested with any of the 1.5.x versions yet, so probably best to stay with 1.4.x.
99
  Make sure that JAVA_HOME environment variable is properly set and that both
100
  java and javac are on your PATH.
101
  </p>
102
  <p class="header">Oracle 8i or Postgres</p>
103
  <p><i>Oracle:</i><br>
104
   The Oracle RDBMS must be installed and running as a daemon on the system.
105
   In addition the JDBC listener must be enabled.  You can enable it by
106
   logging in as your Oracle user and typing the following:
107
   <pre>lsnrctl start</pre>
108
   Your instance should have a table space of at least 5 MB (10 MB or higher 
109
   recommended).  You should also have a username specific to Metacat
110
   created and enabled.  This user must have most normal permissions 
111
   including CREATE SESSION, CREATE TABLE, CREATE INDEX, CREATE TRIGGER, 
112
   EXECUTE PROCEDURE, EXECUTE TYPE, etc.  If an action is unexplainably 
113
   rejected by Metacat it is probably because the user permissions are not
114
   correctly set.
115
  </p>
116
  <p><i>Postgres:</i><br>
117
  Postgres can be easily installed on most linux distributions and on
118
  Windows (using cygwin) and Mac OS X.  Using Fedora Core or RedHat Linux,
119
  you can install the rpms for postgres and then run 
120
  <code>/etc/init.d/postgresql start</code> in order to start the database.
121
  This initializes the data files.  You need to do a bit of configuration
122
  to create a database and set up a user account and allow internet access
123
  via jdbc.  See the postgres documentation for this, but here is a quick 
124
  start:
125
  <ul>
126
     <li>Switch to the "postgres" user account and edit "data/pg_hba.conf", adding the following line to the file:<br>
127
     <code>host   metacat  metacat      127.0.0.1         255.255.255.255   password</code></li>
128
     <li>Edit the "data/postgres.conf" file and uncomment and edit the line
129
     starting with "tcpip_socket" so that it reads 
130
     <code>tcpip_socket = true</code></li>
131
     <li>Run <code>createdb metacat</code> to create a new database</li>
132
     <li>Run <code>psql metacat</code> to log in using the postgres account and create a new "metacat" user account
133
     <ul>
134
        <li>In postgres, run <code>CREATE USER metacat WITH UNENCRYPTED PASSWORD 'apasswordyoulike';</code></li>
135
        <li>This creates a new account called metacat on the database named metacat</li>
136
        <li>Note: there are many ways to do this, so others such as using 
137
        ENCRYPTED passwords will work fine.</li>
138
     </ul>
139
     </li>
140
     <li>Exit the postgres account back to root and restart the postgres 
141
     database with <code>/etc/init.d/postgresql restart</code></li>
142
     <li>Test logging into the postgres db using the metacat account with 
143
     the following command: 
144
     <code>psql -U metacat -W -h localhost metacat</code></li>
145
  </ul>
146
  </p>
147
  <p class="header">Ant</p>
148
  <p>
149
   Ant is a Java based build application similar to Make on UNIX systems.  
150
   It takes in installation parameters from a file in the root installation
151
   directory named "build.xml".  The Metacat CVS module contains a default
152
   build.xml file that may require some modification upon installation.  Ant
153
   should be installed on the system and the "ant" executable shell script 
154
   should be available in the users path. We note that the current build is 
155
   not working with Ant 1.6.x, so you'll need to use an earler version.  We have 
156
   successfully used Ant 1.5.1, 1.5.2, and some earlier versions.
157
  </p>
158
  <p class="header">Tomcat</p>
159
  <p>
160
    Install tomcat into the directory of your choice. The directory in which 
161
    you install Tomcat itself will be referred to as the "$CATALINA_HOME".
162
    We recommend to install Tomcat version 4.0.  More details about 
163
    tomcat installation is avaliable in <a href=" http://jakarta.apache.org/tomcat/index.html">here</a>.
164
  </p>
165
 </td>
166
</tr>
167
</table>
168

    
169
<table class="tabledefault" width="100%">
170
<td class="tablehead" colspan="2"></td>
171
<tr>
172
<td>
173
  <p>
174
   Once all of the prerequisite software is installed as described above, 
175
   the installation of Metacat can begin.  First you must have a current
176
   version of the source distribution of Metacat.  You can get it two ways.
177
   Authorized users can check it out of the NCEAS 
178
   <a href="http://www.nceas.ucsb.edu/cgi-bin/cvsweb.cgi/xmltodb/">CVS</a>
179
   system. You'll need both the "metacat" module and the "utilities" module to
180
   be checked out in sibling directories. The command is as follows: 
181
   <pre>mkdir knb-software</pre>
182
   <pre>cd knb-software</pre>
183
   <pre>cvs checkout -P metacat</pre>
184
   <pre>cvs checkout -P utilities</pre>  
185
   Or you can 
186
   <a href="@server@/software/download.html">download</a> a gzipped tar file
187
   from this site.
188
  </p>
189
  <p><h2>Edit build.xml File</h2></p>
190
  <p>
191
   Once you have either checked out or unzipped and untarred the source
192
   distribution, you can begin the installation process.  Change into the 
193
   metacat directory and edit the file called "build.xml".  You will need 
194
   to change a number of configuration properties to match the setup on
195
   your system.  If you are using oracle, you'll need to customize the
196
   properties in the "oracle" target.  If you are using Postgres, you'll
197
   need to customize the properties in the "postgres" target.  All users
198
   will need to customize the properties in the "config" target.
199
  </p>
200
  <p>
201
   The properties that you need to change will include jdbc-connect, 
202
   dbDriver, dbAdapter, oracle_home, 
203
   jdbc, tomcat, webapps, context, user, server, systemidserver, 
204
   web-base-url, and default-style. Each is described in detail below. 
205
   You should also verify that the jar file properties mentioned in the 
206
   remainder of the config target are accessible at the paths listed -- the 
207
   defaults will usually work.
208
  </p>
209
  <p>
210
   Note that the build file is preconfigured to install Metacat either using 
211
   Oracle or PostgreSQL as a backend database.  To change the database
212
   system, simply change the 'depends' attribute of the 'config' target to be
213
   the name of the database target that you wish to use (either 'oracle' or 
214
   'postgresql').  If you wish to use a different database system, add a new
215
   target for your database with the needed parameters and actions then add it
216
   to the 'depends' attribute.
217
  </p>
218
  Properties you will likely need to change:<br />
219
  <ul>
220
  <li>
221
   The jdbc-connect parameter is the JDBC connection string needed to connect 
222
   to your database.  
223
  </li>
224
  <li>
225
   The dbDriver parameter is the name of the JDBC driver class to use for
226
   connections to your database.
227
  </li>
228
  <li>
229
   The dbAdapter parameter is the name of the Metacat adapter class to be used
230
   to communicate with a particular database.
231
  </li>
232
  <li>
233
   The oracle_home parameter is the location that oracle is installed on 
234
   your system.
235
  </li>
236
  <li>
237
   The jdbc parameter is the location of your jdbc driver jar file.
238
  </li>
239
  <li>
240
   The tomcat parameter is the location in which tomcat is installed.
241
  </li>
242
  <li>
243
   The webapps parameter is the location in which your tomcat servlet
244
   contexts are installed.  This is typically "$TOMCAT_HOME/webapps".
245
  </li>
246
  <li>
247
   The context parameter is the name of the servlet context in which
248
   you want metacat to be installed.  This will determine the installation
249
   directory for the servlet and many of the urls that are used to
250
   access the installed Metacat server.
251
  </li>
252
  <li>
253
   The user and password parameters are the database user name that you set up
254
   to use Metacat, for example an Oracle username and password.
255
  </li>
256
  <li>
257
   The tomcatversion is the version of your Tomcat. You should put tomcat3 or
258
   tomcat4 here.
259
  </li>
260
  <li>
261
   Web-base-url is the URL from which you want to load any stylesheets 
262
   or supplementary images.
263
  </li>
264
  <li>
265
   Server is the http address on which Metacat is running (note that you should
266
   not include the 'http://' in the server property).
267
  </li>
268
  </li>
269
  <li>
270
   The systemidserver is the protocol (http or https) and server location to get 
271
   any DTDs.
272
  </li>
273
  <li>
274
   The datafilepath is the directory to store the data file.
275
  </li>
276
  <li>
277
   The inlinedatafilepath is the directory to store inline data (This is for EML2).
278
  </li>
279
  <li>
280
   The default-style parameter defines the "style-set" that is to be used
281
   by default when the qformat parameter is missing or set to "html" during
282
   a query.  It is set to "knb", which is the only style that ships with the
283
   default metacat distribution.  If you create your own stylesheets for
284
   displaying metacat output, you may want to create a new config file in the
285
   config-dir (e.g., mystyle.xml) and then change the default-style to use
286
   your custom style (e.g., "mystyle").
287
  </li>
288
  <li>
289
   The debuglevel is the control value of debug message. Generally, it will vary 
290
   from 0 to 70. In level 70, Metacat will desplay all debug messages.
291
  </li>
292
   <li>
293
   The forcereplicationwaitingtime is the waiting time for start force replication
294
   after uploading a package. Usually we use default value.
295
  </li>
296
  </ul>
297

    
298
  Other properties that you can but generaly need not change:<br />
299
  <ul>
300
  <li>
301
   The installdir
302
   parameter is the directory in which Ant should install the servlet.
303
   It is your "servlet context path" that was defined above.
304
  </li>
305
  <li>
306
   Replication path is the relative path to the replication servlet.  This
307
   should be the name of your servlet followed by "/servlet/replication".  For
308
   example 'metacat/servlet/replication'.
309
  </li>
310
  <li>
311
   The servlet path is the relative path to your servlet as viewed by the 
312
   Tomcat or Apache web server.  Under Tomcat, the form is usually
313
   <pre>/&lt;servlet-context-name&gt;/servlet/metacat</pre>
314
  </li>
315
  <li>
316
   The html-path is usually the first directory of the servlet-path. The only 
317
   reason it wouldn't be is if you are doing something with your web server
318
   and you want the html served from a different location than where the 
319
   servlet is located.
320
  </li>
321
  <li>
322
   The image-path is where you want the Metacat image files stored.  It
323
   should be a directory that is accessible by the web server.
324
  </li>
325
  <li>
326
   Replication-log is the location at which you want Metacat to place any 
327
   replication log files.  The user that starts Tomcat must have permission to
328
   write to this directory.
329
  </li>
330
  <li>
331
   The config-dir parameter specifies the location of the configuration files
332
   for the "style-sets" feature.  It is set by default to the installation
333
   directory and generally does not need to be changed.
334
  </li>
335
  <li>
336
   The eml-module, eml-version, eml-tag parameters control the installation
337
   behavior with respect to EML.  You should not need to change these paramters.
338
  </li>
339
  <li>
340
   The cvsrootparameter is used when building the distribution and you should
341
   not need to change it.
342
  </li>
343
  </ul>
344
  <p class="emphasis">
345
   Note: DO NOT add a slash [/] to the end of these paths.  Metacat will not
346
   function correctly if you do so.
347
  </p>
348
  <p class="header"><h2>SQL Scripts</h2></p>
349
  <p>
350
   You now need to set up the table structure in your database.  You can do
351
   either do this using the ant build system, or by manually running the
352
   scripts using a sql utility.
353
  </p>
354
  <p><b>WARNING: Do NOT run this on an existing metacat installation as it
355
  will delete all of your data.  If you have an existing metacat installation,
356
  see the instructions for "Upgrading" below.</b></p>
357

    
358
  <p>To run the scripts using ant, type <code>ant installdb</code>.  This does 
359
  not work for postgres, so you'll need to run the xmltables-postgres.sql script 
360
  manually (see next paragraph).
361
  </p>
362
  <p>To run the scripts manually, change to the
363
   metacat/src directory.  Then run you RDBMS's SQL utility.  In Oracle it is
364
   SQLPlus.  This tutorial assumes an Oracle database so this example is for
365
   SQLPlus.  Login as the oracle user that was set up for use with Metacat.
366
   At the SQLPlus prompt type the following: <pre><b>@xmltables.sql;</b></pre>
367
   For postgres, use a command like: 
368
   <code>psql -U metacat -W -h localhost -f build/src/xmltables-postgres.sql metacat</code>
369
  </p>
370
  <p>Either way, 
371
   you should see a bunch of output showing the creation of the Metacat table
372
   space. The first time you run this script you will get several errors at the 
373
   beginning saying that you cannot drop a table/index/trigger because it 
374
   does not exist.  This is normal.  Any other errors besides this need to be
375
   resolved before continuing. The script file name for PostgreSQL is 
376
   xmltalbes_postgres.sql and for Microsoft SQL server is 
377
   xmltables-sqlserver.sql.
378
  </p>
379
  <p>
380
   If the script has run correctly you should be able to type 
381
   <pre>describe xml_documents</pre> and it should tell you
382
   <pre>
383
    Name            Null?         Type
384
    --------------  ------------  ---------------- 
385
     DOCID          NOT NULL      VARCHAR2(250)
386
     ROOTNODEID                   NUMBER(20)
387
     DOCNAME                      VARCHAR2(100)
388
     DOCTYPE                      VARCHAR2(100)
389
     DOCTITLE                     VARCHAR2(1000)
390
     USER_OWNER                   VARCHAR2(100)
391
     USER_UPDATED                 VARCHAR2(100)
392
     SERVER_LOCATION              NUMBER(20)
393
     REV                          NUMBER(10)
394
     DATE_CREATED                 DATE
395
     DATE_UPDATED                 DATE
396
     PUBLIC_ACCESS                NUMBER(1)
397
     UPDATED                      NUMBER(1)
398
   </pre>
399
  </p>
400
  <p class="header"><h2>Upgrading SQL Scripts</h2></p>
401
  <p>
402
    If you have an existing metacat installation, you should not run the install
403
    script because it will replace all of the older tables with new, empty 
404
    copies of the tables.  Thus you would lose your data!  Instead, you can 
405
    run some upgrade scripts that will change the table structure as needed for
406
    the new version.  If you are skipping versions, run each upgrade script
407
    for the intermediate versions as well.  Currently the upgrade scripts are:
408
   </p>
409
    <ul>
410
      <li>upgrade-db-to-1.2.sql</li>
411
      <li>upgrade-db-to-1.3.sql</li>
412
      <li>upgrade-db-to-1.4.sql</li>
413
    </ul>
414
   <p>
415
    So, if you had an existing metacat 1.0 installation and you were upgrading 
416
    to 1.3, you would need to run both upgrade-db-to-1.2.sql and 
417
    upgrade-db-to-1.3.sql. Howver, if you were starting from a Metacat 1.2.x
418
    installation, you would only need to run the 1.3 upgrade script.
419
   </p>
420
  </p>
421
</td>
422
</tr>
423
</table>
424

    
425
<table class="tabledefault" width="100%">
426
<td class="tablehead" colspan="2"><p><h2>Compilation and Installation</h2></p></td>
427
<tr>
428
<td>
429
  <a name="protocol"></a>
430
  <p>
431
   Ant allows compilation and installation to be done in one step.
432
   Change into the metacat directory and type: 
433
   <pre><b>ant geteml install</b></pre>
434
   or, if you are upgrading an existing installation, type:
435
   <pre><b>ant geteml upgrade</b></pre>
436
   <p>
437
   You should see a bunch of messages telling you the progress of compilation
438
   and installation.  When it is done you should see the message 
439
   BUILD SUCCESSFUL
440
   and you should be returned to a UNIX command prompt.  If you do not see
441
   the message BUILD SUCCESSFUL then there was an error that you need to 
442
   resolve.
443
   This may come up if you are logged in as a user that does not have write
444
   access to one or more of the directories that are listed in the build.xml
445
   file, or if any of the paths to files are not configured correctly in the
446
   "config" target.
447
  </p>
448
  <p>Once metacat itself is installed, you should also register
449
  the Ecological Metadata Language (EML) DTDs and schemas. This process is done most
450
  easily by running:</p>
451
  <pre><b>ant dtdschemasql</b></pre> 
452
  <p>This command registers the DTDs' and schemas' location in the 
453
  metacat server.  Your database username and password have to be set correctly
454
  for this to work.
455
  </p>
456
  <p>
457
  Note: The 'data' directory in the installation directory must be writeable
458
  by whatever user is running Tomcat or you will not be able to upload data 
459
  files to the system.
460
  <h2>Restart Tomcat</h2>
461
  <p>
462
   Once you have successfully installed Metacat, there is one more step.  Tomcat
463
   (and Apache if you have Tomcat integrated with it) must be restarted.  To do
464
   this, login as the user that runs your tomcat server (often "tomcat"),
465
   go to $CATALINA_HOME/bin and type:
466
   <pre>
467
   ./shutdown.sh 
468
   ./startup.sh 
469
   </pre>
470
   In the Tomcat startup messages you should see something in log file like:
471
   <pre>
472
    MetacatServlet Initialize
473
    Context log path="/metadata" :Metacat: init
474
    MetacatServlet Initialize
475
   </pre>
476
   If you see that message Tomcat is successfully loading the Metacat servlet.
477
   Next, try to run your new servlet.  Go to a web browser and type:
478
   <pre>http://yourserver.yourdomain.com/yourcontext/</pre>
479
   You should substitute your context name for "yourcontext" in the url above.
480
   If everything is working correctly, you should see a query page followed
481
   by an empty result set.  Note that if you do not have Tomcat integrated with
482
   Apache you will probably have to type
483
   <pre>http://yourserver.yourdomain.com:8080/yourcontext/</pre>
484
  </p>
485
</td>
486
</tr>
487
</table>
488

    
489
</body>
490
</html>
(26-26/48)