Project

General

Profile

metacat / docs / user / metacatinstall.html @ 3627

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: costa $'
9
  *    '$Date: 2007-11-30 13:45:10 -0800 (Fri, 30 Nov 2007) $'
10
  *    '$Revision: 3627 $'
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"><h2>***Disclaimer***</h2></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><a name="The Table of Contents"><h2>The Table of Contents</h2></p></td>
58
<tr>
59
<td>
60
  <ul>
61
     <li>
62
         <a HREF="metacatinstall.html#Operating System Specific Instructions">Operating System Specific Instructions</a>
63
      </li>
64
      <li>
65
         <a HREF="metacatinstall.html#Pre-Installation">Pre-Installation</a>
66
      </li>
67
      <li>
68
         <a HREF="metacatinstall.html#Aditional Software Setup">Aditional Software Setup</a>
69
      </li>
70
      <li>
71
         <a HREF="metacatinstall.html#Edit build.properties File">Edit <code>build.properties</code> File</a>
72
      </li>
73
      <li>
74
         <a HREF="metacatinstall.html#Compilation and Installation">Compilation and Installation</a>
75
      </li>
76
        <li>
77
         <a HREF="metacatinstall.html#Upgrade">Compilation and Upgrading Existing Metacat</a>
78
      </li>
79
      
80
  </ul>
81
</td>
82

    
83
<table class="tabledefault" width="100%">
84
<td class="tablehead" colspan="2"><p><a name="Operating System Specific Instructions"><h2>Operating System Specific Instructions</h2></p></td>
85
<tr>
86
<td>
87
  <p class="emphasis">
88
These documents are meant to outline the metacat installation process on specific platforms. They are <strong><em>not</em></strong> a substitute for the below instructions and only meant as a supplemental guideline. 
89
  </p>
90
  <ul>
91
    <li> <a href="os_specific/install_metacat_windows.html">Installing from CVS source on Windows XP</a> </li>
92
    <li> <a href="os_specific/install_metacat_ubuntu.html">Installing from CVS source on Ubuntu 6.06 (ie Dapper Drake)</a> </li>
93
    <li> <a href="os_specific/install_metacat_mac.html">Installing from CVS source on Mac OS X</a> </li>
94

    
95
  </ul>
96
</td>
97
</tr>
98
</table>
99

    
100

    
101
<table class="tabledefault" width="100%">
102
<td class="tablehead" colspan="2"><p><a name="Pre-Installation"><h2>Pre-Installation</h2></p></td>
103
<tr>
104
<td>
105
  <p class="header">Minimum Requirements</p> 
106
  <p>
107
   Installing Metacat requires a server running an SQL92 compliant database
108
   (Oracle 8i or Postgresql recommended) with at least 128MB RAM, and a Pentium III class
109
   processor or higher.  The amount of disk space required depends on the
110
   size of your RDBMS tablespace (which should be at least 10 MB, 
111
   however Metacat itself requires only about 1 MB of free space after 
112
   installation).  These instructions assume a Linux environment but may
113
   work on other UNIX type environments, however this has not been tested.
114
  </p>
115
  <p class = "header">Additional Required Software</p>
116
  <p>
117
   The server on which you wish to install Metacat must have the following
118
   software installed and running correctly before attempting to install
119
   Metacat.
120
   <ul>
121
     <li><a href="http://www.oracle.com">Oracle 8i</a> (or another SQL92
122
         compliant RDBMS like Postgres)</li>
123
     <li><a href="http://jakarta.apache.org/ant/index.html">Apache Jakarta-Ant</a>
124
     </li>
125
     <li><a href="http://jakarta.apache.org/tomcat/index.html">Apache Jakarta-Tomcat</a>
126
       <p class="emphasis">Note: For a more robust web serving environment, 
127
       Apache web server should
128
       be installed along with Tomcat and the two should be integrated
129
       as described on the Apache web site.</p>
130
     </li>
131
   </ul>
132
  </p>
133
</td>
134
</tr>
135
</table>
136

    
137
<table class="tabledefault" width="100%">
138
<td class="tablehead" colspan="2"><p><a name="Aditional Software Setup"><h2>Aditional Software Setup</h2></p></td>
139
<tr>
140
<td>
141
  <p class="header">Java</p>
142
  <p>You'll need a recent Java SDK; J2SE 1.4.2 or later is required.  The latest metacat release
143
  has been tested most extensively with <a href="http://java.sun.com/j2se/1.5.0/">J2SE 5.0</a>
144
  and this is the recommended version.
145
  Make sure that JAVA_HOME environment variable is properly set and that both
146
  java and javac are on your PATH.
147
  </p>
148
  <p class="header">Oracle 8i or Postgres</p>
149
  <p><i>Oracle:</i><br>
150
   The Oracle RDBMS must be installed and running as a daemon on the system.
151
   In addition the JDBC listener must be enabled.  You can enable it by
152
   logging in as your Oracle user and typing the following:
153
   <pre>lsnrctl start</pre>
154
   Your instance should have a table space of at least 5 MB (10 MB or higher 
155
   recommended).  You should also have a username specific to Metacat
156
   created and enabled.  This user must have most normal permissions 
157
   including CREATE SESSION, CREATE TABLE, CREATE INDEX, CREATE TRIGGER, 
158
   EXECUTE PROCEDURE, EXECUTE TYPE, etc.  If an action is unexplainably 
159
   rejected by Metacat it is probably because the user permissions are not
160
   correctly set.
161
  </p>
162
  <p><i>Postgres:</i><br>
163
  Postgres can be easily installed on most linux distributions and on
164
  Windows (using cygwin) and Mac OS X.  Using Fedora Core or RedHat Linux,
165
  you can install the rpms for postgres and then run 
166
  <code>/etc/init.d/postgresql start</code> in order to start the database. 
167
  On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command
168
  to install postgres: <code>sudo apt-get install postgresql-8.0</code> and 
169
  then run <code>/etc/init.d/postgresql-8.0 start</code> to start.
170
  
171
  This initializes the data files.  You need to do a bit of configuration
172
  to create a database and set up a user account and allow internet access
173
  via jdbc.  See the postgres documentation for this, but here is a quick 
174
  start:
175
  <ul>
176
     <li>Switch to the "postgres" user account and edit "data/pg_hba.conf", adding the following line to the file:<br>
177
     <code>host   metacat  metacat      127.0.0.1         255.255.255.255   password</code><br>
178
     If your host uses IPv6 addresses, you may need this line instead:
179
     <code>host   metacat  metacat      ::1               ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff password</code></li>
180
     <li>If you are using Postgresql pre-8.0, you must edit the "data/postgres.conf" file and uncomment and edit the line
181
     starting with "tcpip_socket" so that it reads 
182
     <code>tcpip_socket = true</code></li>
183
     <li>Run <code>createdb metacat</code> to create a new database</li>
184
     <li>Run <code>psql metacat</code> to log in using the postgres account and create a new "metacat" user account
185
     <ul>
186
        <li>In postgres, run <code>CREATE USER metacat WITH UNENCRYPTED PASSWORD 'apasswordyoulike';</code></li>
187
        <li>This creates a new account called metacat on the database named metacat</li>
188
        <li>Note: there are many ways to do this, so others such as using 
189
        ENCRYPTED passwords will work fine.</li>
190
     </ul>
191
     </li>
192
     <li>Exit the postgres account back to root and restart the postgres 
193
     database with <code>/etc/init.d/postgresql restart</code></li>
194
     <li>Test logging into the postgres db using the metacat account with 
195
     the following command: 
196
     <code>psql -U metacat -W -h localhost metacat</code></li>
197
  </ul>
198
  </p>
199
  <p class="header">Ant</p>
200
  <p>
201
   Ant is a Java based build application similar to Make on UNIX systems.  
202
   It takes in installation parameters from a file in the root installation
203
   directory named "build.xml".  The Metacat CVS module contains a default
204
   build.xml file that may require some modification upon installation.  Ant
205
   should be installed on the system and the "ant" executable shell script 
206
   should be available in the users path. The latest metacat release was tested with 
207
   Ant 1.6.5. <!-- We note that the current build is 
208
   not working with Ant 1.6.x, so you'll need to use an earler version.  We have 
209
   successfully used Ant 1.5.1, 1.5.2, and some earlier versions. -->
210
  </p>
211
  <p class="header">Tomcat</p>
212
  <p>
213
    Install Tomcat into the directory of your choice. The directory in which 
214
    you install Tomcat itself will be referred to as the "$CATALINA_HOME".
215
    We recommend that you install Tomcat version 5.5.  More details about 
216
    Tomcat installation are available <a href=" http://jakarta.apache.org/tomcat/index.html">here</a>.
217
  </p>
218
 </td>
219
</tr>
220
</table>
221

    
222
<table class="tabledefault" width="100%">
223
<td class="tablehead" colspan="2"><p><a name="Edit build.properties File"><h2>Edit <code>build.properties</code> File</h2></p></td>
224
<tr>
225
<td>
226
  <p>
227
   Once all of the prerequisite software is installed as described above, 
228
   the installation of Metacat can begin.  First you must have a current
229
   version of the source distribution of Metacat.  You can get it two ways.
230
   Authorized users can check it out of the NCEAS 
231
   <a href="http://www.nceas.ucsb.edu/cgi-bin/cvsweb.cgi/xmltodb/">CVS</a>
232
   system. You'll need both the "metacat" module and the "utilities" module to
233
   be checked out in sibling directories. The command is as follows: 
234
   <pre>mkdir knb-software</pre>
235
   <pre>cd knb-software</pre>
236
   <pre>cvs checkout -P metacat</pre>
237
   <pre>cvs checkout -P utilities</pre>  
238
   Or you can 
239
   <a href="@server@/software/download.html">download</a> a gzipped tar file
240
   from this site.
241
  </p>
242
   <p>
243
   Once you have either checked out or unzipped and untarred the source
244
   distribution, you can begin the installation process.  Change into the 
245
   metacat directory and edit the file called "<code>build.properties</code>".  You will need 
246
   to change a number of configuration properties to match the setup on
247
   your system. The property values that you will likely need to change are described in 
248
   detail in the following table:
249
  </p>
250
  <br/>
251
  <table border="1">
252
    <tr>
253
      <td><b>Property</b></td>
254
      <td><b>Description</b></td>
255
      <td><b>Default value and examples of other values</b></td>
256
    </tr>
257
    <tr>
258
      <td>tomcat</td>
259
      <td>The tomcat property is the location in which tomcat is installed.</td>
260
      <td>Default:&nbsp;&nbsp;
261
          <code>/usr/local/devtools/jakarta-tomcat</code>
262
      <br><br>Example:&nbsp;&nbsp;
263
          <code>C:/Tomcat-5.5</code></td>
264
    </tr>
265
    <tr>
266
      <td>deploy.dir</td>
267
      <td>The deploy.dir property is the location in which your tomcat servlet 
268
          contexts are deployed. This is typically "${tomcat}/webapps",
269
          where ${tomcat} is the same value that you entered for the 'tomcat'
270
          property above.
271
      </td>
272
      <td>Default:&nbsp;&nbsp;
273
          <code>/var/www/org.ecoinformatics.knb</code>
274
      <br><br>Example:&nbsp;&nbsp;
275
          <code>C:/Tomcat-5.5/webapps</code>
276
      </td>
277
    </tr>
278
    <tr>
279
      <td>tomcatversion</td>
280
      <td>The tomcatversion property is the version of Tomcat in which you 
281
          want Metacat to run. This will determine the location of some
282
          jar files coming with Tomcat. 
283
          <p>
284
            <em>Note: Tomcat 3 and 4 are no longer tested or supported by Metacat.
285
                Users are highly encouraged to upgrade to Tomcat 5.5.
286
            </em>
287
          </p>
288
          <p>
289
            <em>Also note: a property value of 'tomcat5' can be set when using
290
                either Tomcat 5.0 or Tomcat 5.5.
291
            </em>
292
          </p>
293
      </td>
294
      <td>Default:&nbsp;&nbsp;
295
          <code>tomcat5</code>
296
      <br><br>Other possible values (deprecated):&nbsp;&nbsp;
297
          <code>tomcat3 tomcat4</code>
298
      </td>
299
      </td>
300
    </tr>
301
    <tr>
302
      <td>metacat.context</td>
303
      <td>The metacat.context property is the name of the servlet context in which you 
304
          want Metacat to be installed. This will determine the installation 
305
          directory for the servlet and many of the URLs that are used to access
306
          the installed Metacat server.</td>
307
      <td>Default:&nbsp;&nbsp;
308
          <code>knb</code>
309
      <br><br>Example:&nbsp;&nbsp;
310
          <code>mycontext</code>
311
      </td>
312
    </tr>
313
    <tr>
314
      <td>config.hostname</td>
315
      <td>The config.hostname property is the hostname of the server on which Metacat is 
316
          running (note that you should not include the 'http://' in the config.hostname
317
          property).
318
      </td>
319
      <td>Default:&nbsp;&nbsp;
320
         <code>knb.ecoinformatics.org</code>
321
      <br><br>Example:&nbsp;&nbsp;
322
         <code>somehost.university.edu</code>
323
      </td>
324
    </tr>
325
    <tr>
326
      <td>config.port</td>
327
      <td>The config.port property is the HTTP plain port number that is used to connect to Metacat.
328
          If Tomcat is running stand-alone, the value will typically be 8080.</td>
329
      <td>Default:&nbsp;&nbsp;
330
          <code>80</code>
331
      <br><br>Example:&nbsp;&nbsp;
332
          <code>8080</code>
333
      </td>
334
    </tr>
335
    <tr>
336
      <td>config.port.https</td>
337
      <td>The config.port.https property is the HTTP secure port number that is used to connect to Metacat,
338
          generally when replicating documents to and from other Metacat servers.
339
          If Tomcat is running stand-alone, the value will typically be 8443.</td>
340
      <td>Default:&nbsp;&nbsp;
341
          <code>443</code>
342
      <br><br>Example:&nbsp;&nbsp;
343
          <code>8443</code>
344
      </td>
345
    </tr>
346
    <tr>
347
      <td>ldapUrl</td>
348
      <td>URL to the LDAP server. The LDAP server is used in the default
349
          authentication module to authenticate and identify users of the
350
          system.  To participate in the KNB network, you should leave this at
351
          the default.  But it can be changed if you want to use a 
352
          different directory of users.
353
      </td>
354
      <td>Default:&nbsp;&nbsp;
355
          <code>ldap://ldap.ecoinformatics.org/dc=ecoinformatics,dc=org</code>
356
      </td>
357
    </tr>
358
    <tr>
359
      <td>database</td>
360
      <td>Select the database to use for metadata storage.
361
          <p>
362
          The build file is preconfigured to install Metacat either using 
363
          Oracle, PostgreSQL, or Microsoft SQL Server as a backend database.  
364
          To change the database system, simply change the value of the 'database' 
365
          property to be the name of the database target that you wish to use.
366
          </p>
367
          <p>
368
          Valid values are <code>oracle</code>, <code>postgresql</code>, or
369
          <code>sqlserver</code>. <em>Note that sqlserver support is minimal and
370
          probably will not work without substantial changes on your part,
371
          possibly including code changes.  We have not recently tested on 
372
          sqlserver.</em>
373
          </p>
374
      </td>
375
      <td>Default:&nbsp;&nbsp;
376
          <code>postgresql</code>
377
      <br><br>Other possible values:&nbsp;&nbsp;
378
          <code>oracle</code>&nbsp;&nbsp;
379
          <code>sqlserver</code>
380
      </td>
381
    </tr>
382
    <tr>
383
      <td>jdbc-connect</td>
384
      <td>The JDBC connection string used to connect to the database.</td>
385
      <td>Default:&nbsp;&nbsp;
386
          <code>jdbc:postgresql://localhost/metacat</code>
387
      <br><br>Example:&nbsp;&nbsp;
388
          <code>jdbc:oracle:thin:@somehost.university.edu:1521:metacat</code>
389
      </td>
390
    <tr>
391
      <td>jdbc-base</td>
392
      <td>The base directory for locating JDBC jar files. When using the postgresql database, the default setting of './lib' can be used,
393
          while oracle and sqlserver databases will require a different setting since these jar files are not included in the Metacat
394
          distribution.</td>
395
      <td>Default:&nbsp;&nbsp;
396
          <code>./lib</code>
397
      <br><br>Example:&nbsp;&nbsp;
398
          <code>/usr/oracle/jdbc/lib</code><br>
399
      </td>
400
    </tr>
401
    <tr>
402
      <td>user</td>
403
      <td>The database user name that you set up to use Metacat.</td>
404
      <td>Default:&nbsp;&nbsp;
405
          <code>metacat</code>
406
      <br><br>Example:&nbsp;&nbsp;
407
          <code>metacatuser</code>
408
      </td>
409
    </tr>
410
    <tr>
411
      <td>password</td>
412
      <td>The database password that you set up to use Metacat.</td>
413
      <td>Default:&nbsp;&nbsp;
414
          <code>yourPasswordHere</code>
415
      <br><br>Example:&nbsp;&nbsp;
416
          <code>metacat123</code>
417
      </td>
418
    </tr>
419
    <tr>
420
      <td>datafilepath</td>
421
      <td>The datafilepath is the directory to store data files.</td>
422
      <td>Default:&nbsp;&nbsp;
423
          <code>/var/metacat/data</code>
424
      <br><br>Example:&nbsp;&nbsp;
425
          <code>C:/Tomcat-5.5/data/metacat/data</code>
426
      </td>
427
    </tr>
428
    <tr>
429
      <td>inlinedatafilepath</td>
430
      <td>The inlinedatafilepath is the directory to store inline data that
431
          has been extracted from EML documents.</td>
432
      <td>Default:&nbsp;&nbsp;
433
          <code>/var/metacat/inline-data</code>
434
      <br><br>Example:&nbsp;&nbsp;
435
          <code>C:/Tomcat-5.5/data/metacat/inlinedata</code>
436
      </td>
437
    </tr>
438
    <tr>
439
      <td>default-style</td>
440
      <td>The default-style parameter defines the "style-set" that is to be used
441
          by default when the qformat parameter is missing or set to "html"
442
          during a query. It is set to "default", which is one of the styles that 
443
          ships with the default metacat distribution. Other possible settings
444
          are shown in the examples to the right.</td>
445
      <td>Default:&nbsp;&nbsp;
446
          <code>default</code>
447
      <br><br>Examples:<code>esa kepler knb knb2 knp lter ltss nceas nrs obfs pisco specnet</code>
448
      </td>
449
    </tr>
450
    <tr>
451
      <td>administrators</td>
452
      <td>The administrators parameter lists the accounts that are allowed to
453
          perform administrative actions such as rebuilding indices for 
454
          documents. The list can contain more than one account separated
455
          by colons.</td>
456
      <td>Default:&nbsp;&nbsp;
457
          <code>uid=jones,o=NCEAS,dc=ecoinformatics,dc=org</code>
458
      <br><br>Examples:&nbsp;&nbsp;
459
          <code>uid=localadmin,o=ucnrs.org</code>
460
      </td>
461
    </tr>
462
        
463
        <!-- start lsid stuff -->
464
        <tr>
465
      <td>authority.context</td>
466
      <td>This is the context for the (Life Sciences Identifier) LSID authority.
467
        LSID support is an optional feature which can be configured to provide
468
        metacat access to LSID clients. For more information on LSID's see <a href="http://wiki.gbif.org/guidwiki/wikka.php?wakka=LSID">TDWG
469
        site</a>.</td>
470
      <td>Default: <code>authority</code></td>
471
    </tr>
472
        <tr>
473
      <td>config.lsidauthority</td>
474
      <td>This is the name of the LSID authority that this metacat should use.
475
        This authority needs to be defined as SRV record in a DNS.</td>
476
      <td><p>Default: <code>ecoinformatics.org</code></p>
477
        <p>Examples: <code>esa.org</code> or <code>sulphur.ecoinformatics.org</code></p></td>
478
    </tr>
479
    <tr>
480
      <td>install.ecogrid</td>
481
      <td>Enables EarthGrid web services. EarthGrid web services are disabled by default. 
482
          To enable EarthGrid web services (including query, put, authentication and 
483
          identifier interface), set this value to <code>true</code>, and also set the value
484
          of the <em>metacat.dir</em> property as detailed below.</td>
485
      <td>
486
          Default:&nbsp;&nbsp;<code>false</code>
487
      </td>
488
    </tr>
489
    <tr>
490
      <td>metacat.dir</td>
491
      <td>If the <em>install.ecogrid</em> property (see above) is set to <code>true</code>, this
492
          property should be set to the absolute path of the top-level metacat directory.
493
          If <em>install.ecogrid</em> is set to <code>false</code> (the default setting), 
494
          the value of <em>metacat.dir</em> is ignored.          
495
      </td>
496
      <td>Default:&nbsp;&nbsp;<code>/home/tao/project/metacat</code></td>
497
    </tr>
498
  </table>
499
   Note: If property "install.ecogrid" is set to be true(EarthGrid is enabled), you need to change the value of "metacatURL" to your metacat url in
500
   seek/projects/ecogrid/conf/MetacatImpl/classes/metacat.properties file.
501
  <br>
502

    
503
  <p>
504
  Other properties in <code>build.properties</code> that you can (but generally need not) change:
505
  </p>
506

    
507
  <table border="1">
508
    <tr>
509
      <td><b>Property</b></td>
510
      <td><b>Description</b></td>
511
      <td><b>Default value and examples of other values</b></td>
512
    </tr>
513
    <tr>
514
      <td>server</td>
515
      <td>The server property is the hostname and port number of the server that Metacat uses
516
          for replicating documents to and from other Metacat servers, which should be with the secure (HTTPS) port.
517
          Since this property is usually composed of the <code>config.hostname</code> and <code>config.port.https</code> properties (described above),
518
          the default setting can be used in most cases.
519
      </td>
520
      <td>Default:&nbsp;&nbsp;<code>${config.hostname}:${config.port.https}</code></td>
521
    </tr>
522
    <tr>
523
      <td>httpserver</td>
524
      <td>httpserver is the plain HTTP address and port number that Metacat uses for purposes
525
          other than replication. Since this property is usually composed of the <code>config.hosthame</code> and <code>config.port</code>
526
          properties (described above), the default setting can be used in most cases.</td>
527
      <td>Default:&nbsp;&nbsp;<code>${config.hostname}:${config.port}</code>
528
      </td>
529
    </tr>
530
    <tr>
531
      <td>http.protocol</td>
532
      <td>http.protocol is the string used in the leading part of a URL to indicate use of the HTTP protocol.</td>
533
      <td>Default:&nbsp;&nbsp;<code>http</code>
534
      </td>
535
    </tr>
536
    <tr>
537
      <td>config.metacatserver</td>
538
      <td>The URL to the metacat server, composed in part from three other properties (http.protocol, httpserver, and metacat.context).</td>
539
      <td>Default:&nbsp;&nbsp;<code>${http.protocol}://${httpserver}/${metacat.context}/metacat</code>
540
      </td>
541
    </tr>
542
    <tr>
543
      <td>inst.cgi.dir</td>
544
      <td>Installation directory for registry CGI scripts</td>
545
      <td>Default:&nbsp;&nbsp;
546
          <code>/var/www/cgi-knb</code>
547
      </td>
548
    </tr>
549
    <tr>
550
      <td>cgi-prefix</td>
551
      <td>The URL used for executing CGI scripts</td>
552
      <td>Default:&nbsp;&nbsp;
553
          <code>http://${httpserver}/cgi-bin</code>
554
      </td>
555
    </tr>
556
    <tr>
557
      <td>cvsroot</td>
558
      <td>CVS access to retrieve latest EML. Only used by
559
          developers in building the release.</td>
560
      <td>Default:&nbsp;&nbsp;
561
          <code><pre>:ext:${env.USER}@cvs.ecoinformatics.org:/cvs</pre></code>
562
          Example:&nbsp;&nbsp;
563
          <code><pre>:ext:myaccount@cvs.ecoinformatics.org:/cvs</pre></code>
564
      </td>
565
    </tr>
566
    <tr>
567
      <td>knb-site-url</td>
568
      <td>This is the URL to the web context root for the knb site. 
569
          It is used for the qformat=knb skin only.</td>
570
      <td>Default:&nbsp;&nbsp;
571
          <code>http://knb.ecoinformatics.org</code>
572
      </td>
573
    </tr>
574
    <tr>
575
      <td>timedreplication</td>
576
      <td>Determines whether timed replication to other metacat servers is being used.</td>
577
      <td>Default:&nbsp;&nbsp;
578
          <code>false</code>
579
      <br><br>Other possible values:&nbsp;&nbsp;
580
          <code>true</code>
581
      </td>
582
    </tr>
583
    <tr>
584
      <td>firsttimedreplication</td>
585
      <td>The time for starting first timed replication if timedreplication is true.
586
          (See comments in build.properties file for additional details.)</td>
587
      <td>Default:&nbsp;&nbsp;
588
          <code>10:00 PM</code>
589
          <code>&nbsp;</code>
590
      </td>
591
    </tr>
592
    <tr>
593
      <td>timedreplicationinterval</td>
594
      <td>The interval to next timed replication if timedreplication is true.
595
          The value is in milliseconds and default value is 48 hours.</td>
596
      <td>Default:&nbsp;&nbsp;
597
          <code>172800000</code>
598
          <code>&nbsp;</code>
599
      </td>
600
    </tr>
601
    <tr>
602
      <td>forcereplicationwaitingtime</td>
603
      <td>The waiting time before replication is forced to begin after
604
          uploading a package. The default value should usually suffice.</td>
605
      <td>Default:&nbsp;&nbsp;
606
          <code>30000</code>
607
          <code>&nbsp;</code>
608
      </td>
609
    </tr>
610
    <tr>
611
      <td>log.dir</td>
612
      <td>The directory where replication log files are to be written by Metacat.</td>
613
      <td>Default:&nbsp;&nbsp;<code>${tomcat}/logs</code></td>
614
    </tr>
615
    <tr>
616
      <td>moderators</td>
617
      <td>Moderator accounts, in a colon-separated list. Specifies a list of special users who can review a general user's submission. 
618
             Moderators can approve, revise and reject the submission after reviewing. This property is only used in the ESA skin.</td>
619
      <td>Default:&nbsp;&nbsp;<code>cn=knb-prod,o=NCEAS,dc=ecoinformatics,dc=org</code></td>
620
    </tr>
621
    <tr>
622
      <td>allowedSubmitters</td>
623
      <td>Specifies the list of users who should be allowed to submit documents. 
624
          If no value is specified (the default setting), all users will be allowed to submit documents.
625
      </td>
626
      <td>Default:&nbsp;&nbsp;(no value)</td>
627
    </tr>
628
    <tr>
629
      <td>deniedSubmitters</td>
630
      <td>Specify the list of users who should not be allowed to submit documents. 
631
          If no value is specified (the default setting), all users will be allowed to submit documents.</td>
632
      <td>Default:&nbsp;&nbsp;(no value)</td>
633
    </tr>
634
    <tr>
635
      <td>config.metadataLabelLsid</td>
636
      <td> </td>
637
      <td>Default:&nbsp;&nbsp;<code>${config.lsidauthority}</code></td>
638
    </tr>
639
    <tr>
640
      <td>build.dir</td>
641
      <td>The name of the subdirectory that is created when metacat is built by the 'ant' tool.</td>
642
      <td>Default:&nbsp;&nbsp;<code>build</code></td>
643
    </tr>
644
    <tr>
645
      <td>lsid.build.dir</td>
646
      <td>The name of the subdirectory for building the LSID component of metacat.</td>
647
      <td>Default:&nbsp;&nbsp;<code>${build.dir}/lsid</code></td>
648
    </tr>
649
    <tr>
650
      <td>lib.dir</td>
651
      <td>The name of the subdirectory where library (.jar) files and a number of other important files are located.</td>
652
      <td>Default:&nbsp;&nbsp;<code>lib</code></td>
653
    </tr>
654
    <tr>
655
      <td>lsid.lib.dir</td>
656
      <td>The name of the subdirectory where LSID library (.jar) files are located.</td>
657
      <td>Default:&nbsp;&nbsp;<code>${lib.dir}/lsid_lib</code></td>
658
    </tr>
659
    <tr>
660
      <td>lsid.classes.dir</td>
661
      <td>The relative path to the location of Java classes that support LSID.</td>
662
      <td>Default:&nbsp;&nbsp;<code>edu/ucsb/nceas/metacat/lsid</code></td>
663
    </tr>
664
    <tr>
665
      <td>conf.dir</td>
666
      <td>The name of the directory where LSID configuration files are located.</td>
667
      <td>Default:&nbsp;&nbsp;<code>lib/lsid_conf</code></td>
668
    </tr>
669
    <tr>
670
      <td>services.dir</td>
671
      <td>The name of the directory where LSID services configuration files are located.</td>
672
      <td>Default:&nbsp;&nbsp;<code>${conf.dir}/services</code></td>
673
    </tr>
674
    <tr>
675
      <td>webinf.dir</td>
676
      <td>The name of the directory where additional LSID web services files are located.</td>
677
      <td>Default:&nbsp;&nbsp;<code>${conf.dir}/WEB-INF</code></td>
678
    </tr>
679
    <tr>
680
      <td>compile.debug</td>
681
      <td>Indicates whether Java source should be compiled with debug information.</td>
682
      <td>Default:&nbsp;&nbsp;<code>true</code></td>
683
    </tr>
684
    <tr>
685
      <td>compile.deprecation</td>
686
      <td>Indicates whether Java source should be compiled with deprecation information.</td>
687
      <td>Default:&nbsp;&nbsp;<code>false</code></td>
688
    </tr>
689
    <tr>
690
      <td>compile.optimize</td>
691
      <td>Indicates whether Java source should be compiled with optimization.</td>
692
      <td>Default:&nbsp;&nbsp;<code>true</code></td>
693
    </tr>
694
    <tr>
695
      <td>indexPaths</td>
696
      <td>The <em>indexPaths</em> property specifies a comma-separated (potentially long) list 
697
          of indexed paths that can be utilized to improve the
698
          performance of metacat queries. Each component of the <em>indexPaths</em> property
699
          should specify an absolute or relative path (using an XPath-like syntax) to an XML element or 
700
          attribute present in the XML documents being queried. Metacat stores XML 
701
          element and attribute values for indexed paths in a special database table 
702
          that optimizes search performance.
703
          <p>Metacat queries allow you to specify (using the &lt;pathexpr&gt; tag in search query) 
704
          an exact path to which you want
705
          to restrict the search. When the &lt;pathexpr&gt; path that is specified in the query
706
          is a member of the <em>indexPaths</em> list, search results are returned faster 
707
          because metacat can conduct its search using the optimized database table.
708
          <p>
709
          The default value for the <em>indexPaths</em> property contains numerous paths to EML
710
          elements and attributes that are commonly queried by metacat search tools. 
711
          For example, <em>keyword</em> is a
712
          member of this list because it is common for search tools to query
713
          the <em>keyword</em> field in EML documents. For most purposes, the default value will
714
          optimize various types of searches on EML documents and need not be changed.
715
          <p>
716
          For more information about metacat queries, 
717
          see <a href="./metacatquery.html">Queries and Results</a>.
718
      </td>
719
      <td>Default:&nbsp;&nbsp;<code>organizationName,originator/individualName/surName,...</code></td>
720
    </tr>
721
  </table>
722
  <p>
723
  Metacat has a number of additional settable properties in file
724
  <code>lib/metacat.properties</code>. Under most circumstances,
725
  you will not need to modify this file because the properties of interest
726
  to you can be controlled by editing <code>build.properties</code> as
727
  described above. To learn more about Metacat's additional properties,
728
  see <a href="./properties.html">Metacat Properties File</a>.
729
  </p>
730
  <p class="emphasis">
731
   Note: When setting properties, DO NOT add a trailing slash [/] to the end of any paths that are specified.
732
   Metacat will not function correctly if you do so.
733
  </p>
734

    
735
</td>
736
</tr>
737
</table>
738

    
739
<table class="tabledefault" width="100%">
740
<td class="tablehead" colspan="2"><p><a name="Compilation and Installation"><h2>Compilation and Installation</h2></p></td>
741
<tr>
742
<td>
743
  <a name="protocol"></a>
744
  <p>This section is only for a fresh installation. If you are upgrading an existing Metacat, please skip
745
  this section and go to the next one -  <a HREF="metacatinstall.html#Upgrade">Compilation and Upgrading Existing Metacat</a>
746
  <p>    
747
  <h3>Run Ant Build</h3></p>
748
  <p>
749
   Ant allows compilation and installation to be done in one step.
750
   Change into the metacat directory and type: 
751
   <pre><b>ant install</b></pre>
752
   <p>
753
   You should see a bunch of messages telling you the progress of compilation
754
   and installation.  When it is done you should see the message 
755
   BUILD SUCCESSFUL
756
   and you should be returned to a UNIX command prompt.  If you do not see
757
   the message BUILD SUCCESSFUL then there was an error that you need to 
758
   resolve.
759
   This may come up if you are logged in as a user that does not have write
760
   access to one or more of the directories that are listed in the build.xml
761
   file, or if any of the paths to files are not configured correctly in the
762
   "config" target.
763
  </p>
764
  <p>
765
  Note: The 'data' directories that are indicated in the 'datafilepath' and
766
  'inlinedatafilepath' build properties must be writable
767
  by user account under which Tomcat runs or you will not be able to upload 
768
  data files to the system.
769
  </p>
770

    
771
  <p class="header">To install metacat LSID support, adjust the LSID-related
772
    properties in the build.properties files and type:
773
  <p class="header"><b>ant deploy-lsid</b>
774
  <p>    
775
  <h3>SQL Scripts</h3></p>
776
  <p>
777
   You now need to set up the table structure in your database.  You can 
778
   do this either using the ant build system, or by manually running the
779
   scripts using a sql utility.
780
  </p>
781
  <p><b>WARNING: Do NOT run this on an existing metacat installation as it
782
  will delete all of your data.  If you have an existing metacat installation,
783
  see the instructions for <a HREF="metacatinstall.html#Upgrade">"Compilation and Upgrading Existing Metacat"</a> below.</b></p>
784

    
785
  <p>To run the scripts using ant, type
786
   <pre><b>ant installdb</b></pre> 
787
  </p>
788
  <p>To run the scripts manually, change to the
789
   metacat/build/src directory.  Then run you RDBMS's SQL utility.  In Oracle it is
790
   SQLPlus.  This tutorial assumes an Oracle database so this example is for
791
   SQLPlus.  Login as the oracle user that was set up for use with Metacat.
792
   At the SQLPlus prompt type the following: <pre><b>@xmltables.sql;</b></pre>
793
   For postgres, use a command like: 
794
   <code>psql -U metacat -W -h localhost -f build/src/xmltables-postgres.sql metacat</code>
795
  </p>
796
  <p>Either way, 
797
   you should see a bunch of output showing the creation of the Metacat table
798
   space. The first time you run this script you will get several errors at the 
799
   beginning saying that you cannot drop a table/index/trigger because it 
800
   does not exist.  This is normal.  Any other errors besides this need to be
801
   resolved before continuing. The script file name for PostgreSQL is 
802
   xmltables-postgres.sql and for Microsoft SQL server is 
803
   xmltables-sqlserver.sql.
804
  </p>
805
  <p>
806
   If the script has run correctly you should be able to type 
807
   <pre>describe xml_documents</pre> and it should show:
808
   <pre>
809
    Name            Null?         Type
810
    --------------  ------------  ---------------- 
811
     DOCID          NOT NULL      VARCHAR2(250)
812
     ROOTNODEID                   NUMBER(20)
813
     DOCNAME                      VARCHAR2(100)
814
     DOCTYPE                      VARCHAR2(100)
815
     DOCTITLE                     VARCHAR2(1000)
816
     USER_OWNER                   VARCHAR2(100)
817
     USER_UPDATED                 VARCHAR2(100)
818
     SERVER_LOCATION              NUMBER(20)
819
     REV                          NUMBER(10)
820
     DATE_CREATED                 DATE
821
     DATE_UPDATED                 DATE
822
     PUBLIC_ACCESS                NUMBER(1)
823
     UPDATED                      NUMBER(1)
824
   </pre>
825
  </p>
826
  <p><h3>Register schemas and DTDs</h3></p>
827
  <p>Once the tables have been created, you should also register the Ecological
828
  Metadata Language (EML) DTDs and schemas. <b>However, note that you should 
829
  NOT do this if you are upgrading an existing installation -- the upgrade
830
  scripts take care of it for you (see the next section).</b>  If you are
831
  installing new, you can register the schema documents by running:</p>
832
  <pre><b>ant register-schemas</b></pre> 
833
  <p>This command registers the EML DTDs' and schemas' location in the 
834
  metacat server.  Your database username and password have to be set correctly
835
  for this to work.  Also, if for some reason running this script from ant
836
  does not work, you could instead try running "build/src/loaddtdschema.sql"
837
  from your sql utility (but be sure to use the version in the 'build' directory
838
  that has been customized for your installation).
839
  </p>
840
  <h3>Restart Tomcat</h3>
841
  <p>
842
   Once you have successfully installed Metacat, there is one more step.  Tomcat
843
   (and Apache if you have Tomcat integrated with it) must be restarted.  To do
844
   this, login as the user that runs your tomcat server (often "tomcat"),
845
   go to $CATALINA_HOME/bin and type:
846
   <pre>
847
   <b>
848
   ./shutdown.sh 
849
   ./startup.sh
850
   </b> 
851
   </pre>
852
   In the Tomcat startup messages you should see something in the log file like:
853
   <pre>
854
        Metacat: [WARN]: Metacat (1.8.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]
855
   </pre>
856
   If you see that message Tomcat is successfully loading the Metacat servlet.
857
   Next, try to run your new servlet.  Go to a web browser and type:
858
   <pre>http://yourserver.yourdomain.com/yourcontext/</pre>
859
   You should substitute your context name for "yourcontext" in the url above.
860
   If everything is working correctly, you should see a query page followed
861
   by an empty result set.  Note that if you do not have Tomcat integrated with
862
   Apache you will probably have to type
863
   <pre>http://yourserver.yourdomain.com:8080/yourcontext/</pre>
864
  </p>
865
  <p><b>Troubleshooting</b>: If you see something like java.lang.InternalError: 
866
  Can't connect to X11 window server using 'yourservanme:0.0' as the value of the DISPLAY variable.
867
  <p>You should add this line: 
868
  <b>JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</b> at the first line of
869
  catalina.sh file in tomcat bin directory. The reason is that GeoServer uses X11 windows to draw graphics.
870
  </p>
871
  
872
  <h3>Deploy wsdl file (Only for EarthGrid-enabled Metacat installation) </h3>
873
  <p>
874
   Once Tomcat is running successfully, there is another step for EarthGrid-enabled Metacat installation. 
875
   In metacat directory, type:
876
   <pre><b>ant deploy-ecogrid</b></pre> 
877
   It will generate wsdl files for EarthGrid services.
878
   </p>
879

    
880
</td>
881
</tr>
882
</table>
883

    
884
<table class="tabledefault" width="100%">
885
<td class="tablehead" colspan="2"><p><a name="Upgrade"><h2>Compilation and Upgrading Existing Metacat</h2></p></td>
886
<tr>
887
<td>
888
  <a name="protocol"></a>
889
  <p>The following instructions are for upgrading an existing Metacat.
890
  <p><h3>Stop the running Metacat</h3>
891
   <P>To do this, login as the user that runs your tomcat server (often "tomcat"),
892
   go to $CATALINA_HOME/bin and type:
893
   <pre><b>./shutdown.sh</b> </pre>
894
  <p>    
895
  <h3>Run Ant Build</h3>
896
  <p>
897
   Ant allows compilation and upgrading to be done in one step.
898
   Change into the metacat directory and type: 
899
   <pre><b>ant clean upgrade</b></pre>
900
   <p>
901
   You should see a bunch of messages telling you the progress of compilation
902
   and installation.  When it is done you should see the message 
903
   BUILD SUCCESSFUL
904
   and you should be returned to a UNIX command prompt.  If you do not see
905
   the message BUILD SUCCESSFUL then there was an error that you need to 
906
   resolve.
907
   This may come up if you are logged in as a user that does not have write
908
   access to one or more of the directories that are listed in the build.xml
909
   file, or if any of the paths to files are not configured correctly in the
910
   "config" target.
911
  </p>
912
  <p>
913
  Note: The 'data' directories that are indicated in the 'datafilepath' and
914
  'inlinedatafilepath' build properties must be writable
915
  by user account under which Tomcat runs or you will not be able to upload 
916
  data files to the system.
917
  </p>
918

    
919
  <p class="header">To install metacat LSID support, adjust the LSID-related
920
    properties in the build.properties files and type:
921
  <p class="header"><b>ant deploy-lsid</b>
922
 
923
  <p><h3>Upgrade SQL Scripts</h3></p>
924
  <p>
925
    If you have an existing metacat installation, you should not run the install
926
    script because it will replace all of the older tables with new, empty 
927
    copies of the tables.  Thus you would lose your data!  Instead, you can 
928
    run some upgrade scripts that will change the table structure as needed for
929
    the new version.  If you are skipping versions, run each upgrade script
930
    for the intermediate versions as well.  Currently the upgrade scripts are:
931
   </p>
932
    <ul>
933
      <li>build/src/upgrade-db-to-1.2.sql</li>
934
      <li>build/src/upgrade-db-to-1.3.sql</li>
935
      <li>build/src/upgrade-db-to-1.4.sql</li>
936
      <li>build/src/upgrade-db-to-1.5.sql</li>
937
      <li>build/src/upgrade-db-to-1.6.sql</li>
938
      <li>build/src/upgrade-db-to-1.7.sql</li>
939
      <li>build/src/upgrade-db-to-1.8.sql</li>
940
    </ul>
941
   <p>
942
    For example, if you had an existing metacat 1.5 installation and you were upgrading 
943
    to metacat 1.8, you would need to run three scripts in sequence:
944
    upgrade-db-to-1.6.sql, upgrade-db-to-1.7.sql, and upgrade-db-to-1.8.sql. 
945
    However, if you were starting from a Metacat 1.7
946
    installation, you would only need to run the upgrade-db-to-1.8.sql script.
947
    <em>Be sure to use the version of the scripts from the 'build/src' directory: they
948
    are customized for your installation in that directory.</em>
949
   </p>
950
  </p>
951
  <h3>Restart Tomcat</h3>
952
  <p>
953
   Once you have successfully installed Metacat, there is one more step.  Tomcat
954
   (and Apache if you have Tomcat integrated with it) must be restarted.  To do
955
   this, login as the user that runs your tomcat server (often "tomcat"),
956
   go to $CATALINA_HOME/bin and type:
957
   <pre>
958
   <b>
959
   ./startup.sh
960
   </b> 
961
   </pre>
962
   In the Tomcat startup messages you should see something in the log file like:
963
   <pre>
964
        Metacat: [WARN]: Metacat (1.8.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]
965
   </pre>
966
   If you see that message Tomcat is successfully loading the Metacat servlet.
967
   Next, try to run your new servlet.  Go to a web browser and type:
968
   <pre>http://yourserver.yourdomain.com/yourcontext/</pre>
969
   You should substitute your context name for "yourcontext" in the url above.
970
   If everything is working correctly, you should see a query page followed
971
   by an empty result set.  Note that if you do not have Tomcat integrated with
972
   Apache you will probably have to type
973
   <pre>http://yourserver.yourdomain.com:8080/yourcontext/</pre>
974
  </p>
975
  <p><b>Troubleshooting</b>: If you see something like java.lang.InternalError: 
976
  Can't connect to X11 window server using 'yourservanme:0.0' as the value of the DISPLAY variable.
977
  <p>You should add this line: 
978
  <b>JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</b> at the first line of
979
  catalina.sh file in tomcat bin directory. The reason is that GeoServer uses X11 windows to draw graphics.
980
  </p>
981
  
982
  <h3>Deploy wsdl file (Only for EarthGrid-enabled Metacat installation) </h3>
983
  <p>
984
   Once Tomcat is running successfully, there is another step for EarthGrid-enabled Metacat installation. 
985
   In metacat directory, type:
986
   <pre><b>ant deploy-ecogrid</b></pre> 
987
   It will generate wsdl files for EarthGrid services.
988
   </p>
989

    
990
</td>
991
</tr>
992
</table>
993

    
994
</body>
995
</html>