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

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

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

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

    
484
</body>
485
</html>
(25-25/47)