Project

General

Profile

1 878 berkley
<!--
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$'
9 3019 perry
  *    '$Date$'
10
  *    '$Revision$'
11 878 berkley
  *
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 932 jones
   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 878 berkley
</td>
53
</tr>
54
</table>
55
56
<table class="tabledefault" width="100%">
57 3573 barseghian
<td class="tablehead" colspan="2"><p class="emphasis">Operating System Specific Instructions</p></td>
58
<tr>
59
<td>
60
  <p class="emphasis">
61
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.
62
  </p>
63
  <ul>
64 3585 barseghian
    <li> <a href="os_specific/install_metacat_windows.html">Installing from CVS source on Windows XP</a> </li>
65
    <li> <a href="os_specific/install_metacat_ubuntu.html">Installing from CVS source on Ubuntu 6.06 (ie Dapper Drake)</a> </li>
66 3573 barseghian
    <li> <a href="os_specific/install_metacat_mac.html">Installing from CVS source on Mac OS X</a> </li>
67
68
  </ul>
69
</td>
70
</tr>
71
</table>
72
73
74
<table class="tabledefault" width="100%">
75 878 berkley
<td class="tablehead" colspan="2"><p>Pre-Installation</p></td>
76
<tr>
77
<td>
78
  <p class="header">Minimum Requirements</p>
79
  <p>
80
   Installing Metacat requires a server running an SQL92 compliant database
81 3019 perry
   (Oracle 8i or Postgresql recommended) with at least 128MB RAM, and a Pentium III class
82 878 berkley
   processor or higher.  The amount of disk space required depends on the
83
   size of your RDBMS tablespace (which should be at least 10 MB,
84
   however Metacat itself requires only about 1 MB of free space after
85 3214 costa
   installation).  These instructions assume a Linux environment but may
86 878 berkley
   work on other UNIX type environments, however this has not been tested.
87
  </p>
88
  <p class = "header">Additional Required Software</p>
89
  <p>
90
   The server on which you wish to install Metacat must have the following
91
   software installed and running correctly before attempting to install
92
   Metacat.
93
   <ul>
94
     <li><a href="http://www.oracle.com">Oracle 8i</a> (or another SQL92
95 932 jones
         compliant RDBMS like Postgres)</li>
96 878 berkley
     <li><a href="http://jakarta.apache.org/ant/index.html">Apache Jakarta-Ant</a>
97
     </li>
98
     <li><a href="http://jakarta.apache.org/tomcat/index.html">Apache Jakarta-Tomcat</a>
99 932 jones
       <p class="emphasis">Note: For a more robust web serving environment,
100
       Apache web server should
101 878 berkley
       be installed along with Tomcat and the two should be integrated
102
       as described on the Apache web site.</p>
103
     </li>
104
   </ul>
105
  </p>
106
</td>
107
</tr>
108
</table>
109
110
<table class="tabledefault" width="100%">
111
<td class="tablehead" colspan="2"><p>Aditional Software Setup</p></td>
112
<tr>
113
<td>
114 2182 jones
  <p class="header">Java</p>
115 3214 costa
  <p>You'll need a recent Java SDK; J2SE 1.4.2 or later is required.  The latest metacat release
116
  has been tested most extensively with <a href="http://java.sun.com/j2se/1.5.0/">J2SE 5.0</a>
117
  and this is the recommended version.
118 2182 jones
  Make sure that JAVA_HOME environment variable is properly set and that both
119
  java and javac are on your PATH.
120
  </p>
121
  <p class="header">Oracle 8i or Postgres</p>
122
  <p><i>Oracle:</i><br>
123 878 berkley
   The Oracle RDBMS must be installed and running as a daemon on the system.
124
   In addition the JDBC listener must be enabled.  You can enable it by
125
   logging in as your Oracle user and typing the following:
126
   <pre>lsnrctl start</pre>
127
   Your instance should have a table space of at least 5 MB (10 MB or higher
128
   recommended).  You should also have a username specific to Metacat
129
   created and enabled.  This user must have most normal permissions
130
   including CREATE SESSION, CREATE TABLE, CREATE INDEX, CREATE TRIGGER,
131
   EXECUTE PROCEDURE, EXECUTE TYPE, etc.  If an action is unexplainably
132
   rejected by Metacat it is probably because the user permissions are not
133
   correctly set.
134
  </p>
135 2182 jones
  <p><i>Postgres:</i><br>
136
  Postgres can be easily installed on most linux distributions and on
137
  Windows (using cygwin) and Mac OS X.  Using Fedora Core or RedHat Linux,
138
  you can install the rpms for postgres and then run
139 3019 perry
  <code>/etc/init.d/postgresql start</code> in order to start the database.
140
  On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command
141
  to install postgres: <code>sudo apt-get install postgresql-8.0</code> and
142
  then run <code>/etc/init.d/postgresql-8.0 start</code> to start.
143
144 2182 jones
  This initializes the data files.  You need to do a bit of configuration
145
  to create a database and set up a user account and allow internet access
146
  via jdbc.  See the postgres documentation for this, but here is a quick
147
  start:
148
  <ul>
149
     <li>Switch to the "postgres" user account and edit "data/pg_hba.conf", adding the following line to the file:<br>
150 2455 jones
     <code>host   metacat  metacat      127.0.0.1         255.255.255.255   password</code><br>
151
     If your host uses IPv6 addresses, you made need this line instead:
152
     <code>host   metacat  metacat      ::1               ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff password</code></li>
153 3019 perry
     <li>If you are using Postgresql pre-8.0, you must edit the "data/postgres.conf" file and uncomment and edit the line
154 2182 jones
     starting with "tcpip_socket" so that it reads
155
     <code>tcpip_socket = true</code></li>
156
     <li>Run <code>createdb metacat</code> to create a new database</li>
157
     <li>Run <code>psql metacat</code> to log in using the postgres account and create a new "metacat" user account
158
     <ul>
159
        <li>In postgres, run <code>CREATE USER metacat WITH UNENCRYPTED PASSWORD 'apasswordyoulike';</code></li>
160
        <li>This creates a new account called metacat on the database named metacat</li>
161
        <li>Note: there are many ways to do this, so others such as using
162
        ENCRYPTED passwords will work fine.</li>
163
     </ul>
164
     </li>
165
     <li>Exit the postgres account back to root and restart the postgres
166
     database with <code>/etc/init.d/postgresql restart</code></li>
167
     <li>Test logging into the postgres db using the metacat account with
168
     the following command:
169
     <code>psql -U metacat -W -h localhost metacat</code></li>
170
  </ul>
171
  </p>
172 878 berkley
  <p class="header">Ant</p>
173
  <p>
174
   Ant is a Java based build application similar to Make on UNIX systems.
175
   It takes in installation parameters from a file in the root installation
176
   directory named "build.xml".  The Metacat CVS module contains a default
177
   build.xml file that may require some modification upon installation.  Ant
178 932 jones
   should be installed on the system and the "ant" executable shell script
179 3019 perry
   should be available in the users path. The latest metacat release was tested with
180
   Ant 1.6.5. <!-- We note that the current build is
181 2182 jones
   not working with Ant 1.6.x, so you'll need to use an earler version.  We have
182 3019 perry
   successfully used Ant 1.5.1, 1.5.2, and some earlier versions. -->
183 878 berkley
  </p>
184
  <p class="header">Tomcat</p>
185
  <p>
186 2302 costa
    Install Tomcat into the directory of your choice. The directory in which
187 1770 tao
    you install Tomcat itself will be referred to as the "$CATALINA_HOME".
188 3214 costa
    We recommend that you install Tomcat version 5.5.  More details about
189
    Tomcat installation are available <a href=" http://jakarta.apache.org/tomcat/index.html">here</a>.
190 878 berkley
  </p>
191 1770 tao
 </td>
192 878 berkley
</tr>
193
</table>
194
195
<table class="tabledefault" width="100%">
196 1770 tao
<td class="tablehead" colspan="2"></td>
197 878 berkley
<tr>
198
<td>
199
  <p>
200
   Once all of the prerequisite software is installed as described above,
201
   the installation of Metacat can begin.  First you must have a current
202
   version of the source distribution of Metacat.  You can get it two ways.
203
   Authorized users can check it out of the NCEAS
204
   <a href="http://www.nceas.ucsb.edu/cgi-bin/cvsweb.cgi/xmltodb/">CVS</a>
205 2183 jones
   system. You'll need both the "metacat" module and the "utilities" module to
206
   be checked out in sibling directories. The command is as follows:
207
   <pre>mkdir knb-software</pre>
208
   <pre>cd knb-software</pre>
209
   <pre>cvs checkout -P metacat</pre>
210
   <pre>cvs checkout -P utilities</pre>
211
   Or you can
212 878 berkley
   <a href="@server@/software/download.html">download</a> a gzipped tar file
213
   from this site.
214
  </p>
215 3591 costa
216
  <p>
217
  <a name="buildProperties" />
218
  <h2>Edit <code>build.properties</code> File</h2>
219
  </p>
220 878 berkley
  <p>
221
   Once you have either checked out or unzipped and untarred the source
222
   distribution, you can begin the installation process.  Change into the
223 2302 costa
   metacat directory and edit the file called "<code>build.properties</code>".  You will need
224 932 jones
   to change a number of configuration properties to match the setup on
225 3591 costa
   your system. The property values that you will likely need to change are described in
226
   detail in the following table:
227 878 berkley
  </p>
228 3591 costa
  <br/>
229 2302 costa
  <table border="1">
230
    <tr>
231
      <td><b>Property</b></td>
232
      <td><b>Description</b></td>
233
      <td><b>Default value and examples of other values</b></td>
234
    </tr>
235
    <tr>
236
      <td>tomcat</td>
237
      <td>The tomcat property is the location in which tomcat is installed.</td>
238
      <td>Default:&nbsp;&nbsp;
239
          <code>/usr/local/devtools/jakarta-tomcat</code>
240
      <br><br>Example:&nbsp;&nbsp;
241 3214 costa
          <code>C:/Tomcat-5.5</code></td>
242 2302 costa
    </tr>
243
    <tr>
244 3214 costa
      <td>deploy.dir</td>
245
      <td>The deploy.dir property is the location in which your tomcat servlet
246
          contexts are deployed. This is typically "${tomcat}/webapps",
247
          where ${tomcat} is the same value that you entered for the 'tomcat'
248 2302 costa
          property above.
249
      </td>
250
      <td>Default:&nbsp;&nbsp;
251
          <code>/var/www/org.ecoinformatics.knb</code>
252
      <br><br>Example:&nbsp;&nbsp;
253 3214 costa
          <code>C:/Tomcat-5.5/webapps</code>
254 2302 costa
      </td>
255
    </tr>
256
    <tr>
257 3377 tao
      <td>tomcatversion</td>
258 3591 costa
      <td>The tomcatversion property is the version of Tomcat in which you
259 3377 tao
          want Metacat to run. This will determine the location of some
260 3591 costa
          jar files coming with Tomcat.
261
          <p>
262
            <em>Note: Tomcat 3 and 4 are no longer tested or supported by Metacat.
263
                Users are highly encouraged to upgrade to Tomcat 5.5.
264
            </em>
265
          </p>
266
          <p>
267
            <em>Also note: a property value of 'tomcat5' can be set when using
268
                either Tomcat 5.0 or Tomcat 5.5.
269
            </em>
270
          </p>
271
      </td>
272 3377 tao
      <td>Default:&nbsp;&nbsp;
273
          <code>tomcat5</code>
274 3591 costa
      <br><br>Other possible values (deprecated):&nbsp;&nbsp;
275
          <code>tomcat3 tomcat4</code>
276 3377 tao
      </td>
277 3591 costa
      </td>
278 3377 tao
    </tr>
279
    <tr>
280 3214 costa
      <td>metacat.context</td>
281
      <td>The metacat.context property is the name of the servlet context in which you
282 2302 costa
          want Metacat to be installed. This will determine the installation
283
          directory for the servlet and many of the URLs that are used to access
284
          the installed Metacat server.</td>
285
      <td>Default:&nbsp;&nbsp;
286
          <code>knb</code>
287
      <br><br>Example:&nbsp;&nbsp;
288
          <code>mycontext</code>
289
      </td>
290
    </tr>
291
    <tr>
292 3214 costa
      <td>config.hostname</td>
293
      <td>The config.hostname property is the hostname of the server on which Metacat is
294 3216 tao
          running (note that you should not include the 'http://' in the config.hostname
295 3214 costa
          property).
296 2309 jones
      </td>
297 2302 costa
      <td>Default:&nbsp;&nbsp;
298
         <code>knb.ecoinformatics.org</code>
299
      <br><br>Example:&nbsp;&nbsp;
300 3214 costa
         <code>somehost.university.edu</code>
301 2302 costa
      </td>
302
    </tr>
303
    <tr>
304 3214 costa
      <td>config.port</td>
305
      <td>The config.port property is the HTTP plain port number that is used to connect to Metacat.
306
          If Tomcat is running stand-alone, the value will typically be 8080.</td>
307 2302 costa
      <td>Default:&nbsp;&nbsp;
308 3214 costa
          <code>80</code>
309 2302 costa
      <br><br>Example:&nbsp;&nbsp;
310 3214 costa
          <code>8080</code>
311 2302 costa
      </td>
312
    </tr>
313
    <tr>
314 3214 costa
      <td>config.port.https</td>
315 3215 costa
      <td>The config.port.https property is the HTTP secure port number that is used to connect to Metacat,
316
          generally when replicating documents to and from other Metacat servers.
317 3214 costa
          If Tomcat is running stand-alone, the value will typically be 8443.</td>
318
      <td>Default:&nbsp;&nbsp;
319 3377 tao
          <code>443</code>
320 3214 costa
      <br><br>Example:&nbsp;&nbsp;
321
          <code>8443</code>
322
      </td>
323
    </tr>
324
    <tr>
325 2302 costa
      <td>ldapUrl</td>
326 2309 jones
      <td>URL to the LDAP server. The LDAP server is used in the default
327
          authentication module to authenticate and identify users of the
328
          system.  To participate in the KNB network, you should leave this at
329
          the default.  But it can be changed if you want to use a
330
          different directory of users.
331
      </td>
332 2302 costa
      <td>Default:&nbsp;&nbsp;
333
          <code>ldap://ldap.ecoinformatics.org/dc=ecoinformatics,dc=org</code>
334
      </td>
335
    </tr>
336
    <tr>
337
      <td>database</td>
338
      <td>Select the database to use for metadata storage.
339 3591 costa
          <p>
340
          The build file is preconfigured to install Metacat either using
341
          Oracle, PostgreSQL, or Microsoft SQL Server as a backend database.
342
          To change the database system, simply change the value of the 'database'
343
          property to be the name of the database target that you wish to use.
344
          </p>
345
          <p>
346 2302 costa
          Valid values are <code>oracle</code>, <code>postgresql</code>, or
347 3214 costa
          <code>sqlserver</code>. <em>Note that sqlserver support is minimal and
348 2309 jones
          probably will not work without substantial changes on your part,
349 3214 costa
          possibly including code changes.  We have not recently tested on
350
          sqlserver.</em>
351 3591 costa
          </p>
352 2302 costa
      </td>
353
      <td>Default:&nbsp;&nbsp;
354 3214 costa
          <code>postgresql</code>
355 2302 costa
      <br><br>Other possible values:&nbsp;&nbsp;
356 3214 costa
          <code>oracle</code>&nbsp;&nbsp;
357 2302 costa
          <code>sqlserver</code>
358
      </td>
359
    </tr>
360
    <tr>
361
      <td>jdbc-connect</td>
362
      <td>The JDBC connection string used to connect to the database.</td>
363
      <td>Default:&nbsp;&nbsp;
364 3591 costa
          <code>jdbc:postgresql://localhost/metacat</code>
365 3214 costa
      <br><br>Example:&nbsp;&nbsp;
366
          <code>jdbc:oracle:thin:@somehost.university.edu:1521:metacat</code>
367 2302 costa
      </td>
368
    <tr>
369
      <td>jdbc-base</td>
370 3214 costa
      <td>The base directory for locating JDBC jar files. When using the postgresql database, the default setting of './lib' can be used,
371
          while oracle and sqlserver databases will require a different setting since these jar files are not included in the Metacat
372
          distribution.</td>
373 2302 costa
      <td>Default:&nbsp;&nbsp;
374 3214 costa
          <code>./lib</code>
375 2302 costa
      <br><br>Example:&nbsp;&nbsp;
376 3214 costa
          <code>/usr/oracle/jdbc/lib</code><br>
377 2302 costa
      </td>
378
    </tr>
379
    <tr>
380
      <td>user</td>
381 3214 costa
      <td>The database user name that you set up to use Metacat.</td>
382 2302 costa
      <td>Default:&nbsp;&nbsp;
383 3214 costa
          <code>metacat</code>
384 2302 costa
      <br><br>Example:&nbsp;&nbsp;
385 3214 costa
          <code>metacatuser</code>
386 2302 costa
      </td>
387
    </tr>
388
    <tr>
389
      <td>password</td>
390
      <td>The database password that you set up to use Metacat.</td>
391
      <td>Default:&nbsp;&nbsp;
392
          <code>yourPasswordHere</code>
393
      <br><br>Example:&nbsp;&nbsp;
394
          <code>metacat123</code>
395
      </td>
396
    </tr>
397
    <tr>
398
      <td>datafilepath</td>
399 2309 jones
      <td>The datafilepath is the directory to store data files.</td>
400 2302 costa
      <td>Default:&nbsp;&nbsp;
401
          <code>/var/metacat/data</code>
402
      <br><br>Example:&nbsp;&nbsp;
403 3214 costa
          <code>C:/Tomcat-5.5/data/metacat/data</code>
404 2302 costa
      </td>
405
    </tr>
406
    <tr>
407
      <td>inlinedatafilepath</td>
408 2309 jones
      <td>The inlinedatafilepath is the directory to store inline data that
409
          has been extracted from EML documents.</td>
410 2302 costa
      <td>Default:&nbsp;&nbsp;
411
          <code>/var/metacat/inline-data</code>
412
      <br><br>Example:&nbsp;&nbsp;
413 3214 costa
          <code>C:/Tomcat-5.5/data/metacat/inlinedata</code>
414 2302 costa
      </td>
415
    </tr>
416
    <tr>
417
      <td>default-style</td>
418
      <td>The default-style parameter defines the "style-set" that is to be used
419
          by default when the qformat parameter is missing or set to "html"
420 3214 costa
          during a query. It is set to "default", which is one of the styles that
421 2302 costa
          ships with the default metacat distribution. Other possible settings
422
          are shown in the examples to the right.</td>
423
      <td>Default:&nbsp;&nbsp;
424 3214 costa
          <code>default</code>
425
      <br><br>Examples:<code>esa kepler knb knb2 knp lter ltss nceas nrs obfs pisco specnet</code>
426 2302 costa
      </td>
427
    </tr>
428 2309 jones
    <tr>
429
      <td>administrators</td>
430
      <td>The administrators parameter lists the accounts that are allowed to
431
          perform administrative actions such as rebuilding indices for
432 3214 costa
          documents. The list can contain more than one account separated
433 2309 jones
          by colons.</td>
434
      <td>Default:&nbsp;&nbsp;
435
          <code>uid=jones,o=NCEAS,dc=ecoinformatics,dc=org</code>
436
      <br><br>Examples:&nbsp;&nbsp;
437
          <code>uid=localadmin,o=ucnrs.org</code>
438
      </td>
439
    </tr>
440 2903 harris
441
	<!-- start lsid stuff -->
442
	<tr>
443
      <td>authority.context</td>
444
      <td>This is the context for the (Life Sciences Identifier) LSID authority.
445
        LSID support is an optional feature which can be configured to provide
446
        metacat access to LSID clients. For more information on LSID's see <a href="http://wiki.gbif.org/guidwiki/wikka.php?wakka=LSID">TDWG
447
        site</a>.</td>
448 3591 costa
      <td>Default: <code>authority</code></td>
449 2903 harris
    </tr>
450
	<tr>
451
      <td>config.lsidauthority</td>
452
      <td>This is the name of the LSID authority that this metacat should use.
453
        This authority needs to be defined as SRV record in a DNS.</td>
454 3591 costa
      <td><p>Default: <code>ecoinformatics.org</code></p>
455
        <p>Examples: <code>esa.org</code> or <code>sulphur.ecoinformatics.org</code></p></td>
456 2903 harris
    </tr>
457 3591 costa
    <tr>
458
      <td>install.ecogrid</td>
459
      <td>Enables EarthGrid web services. EarthGrid web services are disabled by default.
460
          To enable EarthGrid web services (including query, put, authentication and
461
          identifier interface), set this value to <code>true</code>, and also set the value
462
          of the <em>metacat.dir</em> property as detailed below.</td>
463
      <td>
464
          Default:&nbsp;&nbsp;<code>false</code>
465
      </td>
466
    </tr>
467
    <tr>
468
      <td>metacat.dir</td>
469
      <td>If the <em>install.ecogrid</em> property (see above) is set to <code>true</code>, this
470
          property should be set to the absolute path of the top-level metacat directory.
471
          If <em>install.ecogrid</em> is set to <code>false</code> (the default setting),
472
          the value of <em>metacat.dir</em> is ignored.
473
      </td>
474
      <td>Default:&nbsp;&nbsp;<code>/home/tao/project/metacat</code></td>
475
    </tr>
476 2302 costa
  </table>
477 3591 costa
478 2302 costa
  <br>
479 3591 costa
480 989 berkley
  <p>
481 3591 costa
  Other properties in <code>build.properties</code> that you can (but generally need not) change:
482 989 berkley
  </p>
483 3591 costa
484 2302 costa
  <table border="1">
485
    <tr>
486
      <td><b>Property</b></td>
487
      <td><b>Description</b></td>
488
      <td><b>Default value and examples of other values</b></td>
489
    </tr>
490
    <tr>
491 3215 costa
      <td>server</td>
492
      <td>The server property is the hostname and port number of the server that Metacat uses
493
          for replicating documents to and from other Metacat servers, which should be with the secure (HTTPS) port.
494
          Since this property is usually composed of the <code>config.hostname</code> and <code>config.port.https</code> properties (described above),
495
          the default setting can be used in most cases.
496
      </td>
497 3591 costa
      <td>Default:&nbsp;&nbsp;<code>${config.hostname}:${config.port.https}</code></td>
498 3215 costa
    </tr>
499
    <tr>
500
      <td>httpserver</td>
501
      <td>httpserver is the plain HTTP address and port number that Metacat uses for purposes
502
          other than replication. Since this property is usually composed of the <code>config.hosthame</code> and <code>config.port</code>
503
          properties (described above), the default setting can be used in most cases.</td>
504
      <td>Default:&nbsp;&nbsp;<code>${config.hostname}:${config.port}</code>
505
      </td>
506
    </tr>
507
    <tr>
508 3591 costa
      <td>http.protocol</td>
509
      <td>http.protocol is the string used in the leading part of a URL to indicate use of the HTTP protocol.</td>
510
      <td>Default:&nbsp;&nbsp;<code>http</code>
511
      </td>
512
    </tr>
513
    <tr>
514
      <td>config.metacatserver</td>
515
      <td>The URL to the metacat server, composed in part from three other properties (http.protocol, httpserver, and metacat.context).</td>
516
      <td>Default:&nbsp;&nbsp;<code>${http.protocol}://${httpserver}/${metacat.context}/metacat</code>
517
      </td>
518
    </tr>
519
    <tr>
520 2302 costa
      <td>inst.cgi.dir</td>
521
      <td>Installation directory for registry CGI scripts</td>
522
      <td>Default:&nbsp;&nbsp;
523
          <code>/var/www/cgi-knb</code>
524
      </td>
525
    </tr>
526
    <tr>
527
      <td>cgi-prefix</td>
528 3591 costa
      <td>The URL used for executing CGI scripts</td>
529 2302 costa
      <td>Default:&nbsp;&nbsp;
530 3214 costa
          <code>http://${httpserver}/cgi-bin</code>
531 2302 costa
      </td>
532
    </tr>
533
    <tr>
534 3214 costa
      <td>cvsroot</td>
535
      <td>CVS access to retrieve latest EML. Only used by
536
          developers in building the release.</td>
537
      <td>Default:&nbsp;&nbsp;
538
          <code><pre>:ext:${env.USER}@cvs.ecoinformatics.org:/cvs</pre></code>
539
          Example:&nbsp;&nbsp;
540
          <code><pre>:ext:myaccount@cvs.ecoinformatics.org:/cvs</pre></code>
541
      </td>
542
    </tr>
543
    <tr>
544 2302 costa
      <td>knb-site-url</td>
545
      <td>This is the URL to the web context root for the knb site.
546
          It is used for the qformat=knb skin only.</td>
547
      <td>Default:&nbsp;&nbsp;
548
          <code>http://knb.ecoinformatics.org</code>
549
      </td>
550
    </tr>
551
    <tr>
552 3214 costa
      <td>timedreplication</td>
553
      <td>Determines whether timed replication to other metacat servers is being used.</td>
554
      <td>Default:&nbsp;&nbsp;
555
          <code>false</code>
556
      <br><br>Other possible values:&nbsp;&nbsp;
557
          <code>true</code>
558
      </td>
559
    </tr>
560
    <tr>
561
      <td>firsttimedreplication</td>
562
      <td>The time for starting first timed replication if timedreplication is true.
563
          (See comments in build.properties file for additional details.)</td>
564
      <td>Default:&nbsp;&nbsp;
565
          <code>10:00 PM</code>
566
          <code>&nbsp;</code>
567
      </td>
568
    </tr>
569
    <tr>
570
      <td>timedreplicationinterval</td>
571
      <td>The interval to next timed replication if timedreplication is true.
572
          The value is in milliseconds and default value is 48 hours.</td>
573
      <td>Default:&nbsp;&nbsp;
574
          <code>172800000</code>
575
          <code>&nbsp;</code>
576
      </td>
577
    </tr>
578
    <tr>
579 2302 costa
      <td>forcereplicationwaitingtime</td>
580
      <td>The waiting time before replication is forced to begin after
581
          uploading a package. The default value should usually suffice.</td>
582
      <td>Default:&nbsp;&nbsp;
583
          <code>30000</code>
584
          <code>&nbsp;</code>
585
      </td>
586
    </tr>
587 3591 costa
    <tr>
588
      <td>log.dir</td>
589
      <td>The directory where replication log files are to be written by Metacat.</td>
590
      <td>Default:&nbsp;&nbsp;<code>${tomcat}/logs</code></td>
591
    </tr>
592
    <tr>
593
      <td>moderators</td>
594
      <td>Moderator accounts, in a colon-separated list. Specifies a list of special users who can review a general user's submission.
595
             Moderators can approve, revise and reject the submission after reviewing. This property is only used in the ESA skin.</td>
596
      <td>Default:&nbsp;&nbsp;<code>cn=knb-prod,o=NCEAS,dc=ecoinformatics,dc=org</code></td>
597
    </tr>
598
    <tr>
599
      <td>allowedSubmitters</td>
600
      <td>Specifies the list of users who should be allowed to submit documents.
601
          If no value is specified (the default setting), all users will be allowed to submit documents.
602
      </td>
603
      <td>Default:&nbsp;&nbsp;(no value)</td>
604
    </tr>
605
    <tr>
606
      <td>deniedSubmitters</td>
607
      <td>Specify the list of users who should not be allowed to submit documents.
608
          If no value is specified (the default setting), all users will be allowed to submit documents.</td>
609
      <td>Default:&nbsp;&nbsp;(no value)</td>
610
    </tr>
611
    <tr>
612
      <td>config.metadataLabelLsid</td>
613
      <td> </td>
614
      <td>Default:&nbsp;&nbsp;<code>${config.lsidauthority}</code></td>
615
    </tr>
616
    <tr>
617
      <td>build.dir</td>
618
      <td>The name of the subdirectory that is created when metacat is built by the 'ant' tool.</td>
619
      <td>Default:&nbsp;&nbsp;<code>build</code></td>
620
    </tr>
621
    <tr>
622
      <td>lsid.build.dir</td>
623
      <td>The name of the subdirectory for building the LSID component of metacat.</td>
624
      <td>Default:&nbsp;&nbsp;<code>${build.dir}/lsid</code></td>
625
    </tr>
626
    <tr>
627
      <td>lib.dir</td>
628
      <td>The name of the subdirectory where library (.jar) files and a number of other important files are located.</td>
629
      <td>Default:&nbsp;&nbsp;<code>lib</code></td>
630
    </tr>
631
    <tr>
632
      <td>lsid.lib.dir</td>
633
      <td>The name of the subdirectory where LSID library (.jar) files are located.</td>
634
      <td>Default:&nbsp;&nbsp;<code>${lib.dir}/lsid_lib</code></td>
635
    </tr>
636
    <tr>
637
      <td>lsid.classes.dir</td>
638
      <td>The relative path to the location of Java classes that support LSID.</td>
639
      <td>Default:&nbsp;&nbsp;<code>edu/ucsb/nceas/metacat/lsid</code></td>
640
    </tr>
641
    <tr>
642
      <td>conf.dir</td>
643
      <td>The name of the directory where LSID configuration files are located.</td>
644
      <td>Default:&nbsp;&nbsp;<code>lib/lsid_conf</code></td>
645
    </tr>
646
    <tr>
647
      <td>services.dir</td>
648
      <td>The name of the directory where LSID services configuration files are located.</td>
649
      <td>Default:&nbsp;&nbsp;<code>${conf.dir}/services</code></td>
650
    </tr>
651
    <tr>
652
      <td>webinf.dir</td>
653
      <td>The name of the directory where additional LSID web services files are located.</td>
654
      <td>Default:&nbsp;&nbsp;<code>${conf.dir}/WEB-INF</code></td>
655
    </tr>
656
    <tr>
657
      <td>compile.debug</td>
658
      <td>Indicates whether Java source should be compiled with debug information.</td>
659
      <td>Default:&nbsp;&nbsp;<code>true</code></td>
660
    </tr>
661
    <tr>
662
      <td>compile.deprecation</td>
663
      <td>Indicates whether Java source should be compiled with deprecation information.</td>
664
      <td>Default:&nbsp;&nbsp;<code>false</code></td>
665
    </tr>
666
    <tr>
667
      <td>compile.optimize</td>
668
      <td>Indicates whether Java source should be compiled with optimization.</td>
669
      <td>Default:&nbsp;&nbsp;<code>true</code></td>
670
    </tr>
671
    <tr>
672
      <td>indexPaths</td>
673
      <td>The <em>indexPaths</em> property specifies a comma-separated (potentially long) list
674
          of indexed paths that can be utilized to improve the
675
          performance of metacat queries. Each component of the <em>indexPaths</em> property
676
          should specify an absolute or relative path (using an XPath-like syntax) to an XML element or
677
          attribute present in the XML documents being queried. Metacat stores XML
678
          element and attribute values for indexed paths in a special database table
679
          that optimizes search performance.
680
          <p>Metacat queries allow you to specify (using the &lt;pathexpr&gt; tag in search query)
681
          an exact path to which you want
682
          to restrict the search. When the &lt;pathexpr&gt; path that is specified in the query
683
          is a member of the <em>indexPaths</em> list, search results are returned faster
684
          because metacat can conduct its search using the optimized database table.
685
          <p>
686
          The default value for the <em>indexPaths</em> property contains numerous paths to EML
687
          elements and attributes that are commonly queried by metacat search tools.
688
          For example, <em>keyword</em> is a
689
          member of this list because it is common for search tools to query
690
          the <em>keyword</em> field in EML documents. For most purposes, the default value will
691
          optimize various types of searches on EML documents and need not be changed.
692
          <p>
693
          For more information about metacat queries,
694
          see <a href="./metacatquery.html">Queries and Results</a>.
695
      </td>
696
      <td>Default:&nbsp;&nbsp;<code>organizationName,originator/individualName/surName,...</code></td>
697
    </tr>
698 2302 costa
  </table>
699
  <p>
700
  Metacat has a number of additional settable properties in file
701 3214 costa
  <code>lib/metacat.properties</code>. Under most circumstances,
702 2302 costa
  you will not need to modify this file because the properties of interest
703
  to you can be controlled by editing <code>build.properties</code> as
704
  described above. To learn more about Metacat's additional properties,
705
  see <a href="./properties.html">Metacat Properties File</a>.
706
  </p>
707 878 berkley
  <p class="emphasis">
708 2302 costa
   Note: When setting properties, DO NOT add a trailing slash [/] to the end of any paths that are specified.
709
   Metacat will not function correctly if you do so.
710 878 berkley
  </p>
711 2322 jones
712
</td>
713
</tr>
714
</table>
715
716
<table class="tabledefault" width="100%">
717
<td class="tablehead" colspan="2"><p><h2>Compilation and Installation</h2></p></td>
718
<tr>
719
<td>
720
  <a name="protocol"></a>
721
  <p>
722
   Ant allows compilation and installation to be done in one step.
723
   Change into the metacat directory and type:
724
   <pre><b>ant install</b></pre>
725
   or, if you are upgrading an existing installation, type:
726
   <pre><b>ant clean upgrade</b></pre>
727
   <p>
728
   You should see a bunch of messages telling you the progress of compilation
729
   and installation.  When it is done you should see the message
730
   BUILD SUCCESSFUL
731
   and you should be returned to a UNIX command prompt.  If you do not see
732
   the message BUILD SUCCESSFUL then there was an error that you need to
733
   resolve.
734
   This may come up if you are logged in as a user that does not have write
735
   access to one or more of the directories that are listed in the build.xml
736
   file, or if any of the paths to files are not configured correctly in the
737
   "config" target.
738
  </p>
739
  <p>
740
  Note: The 'data' directories that are indicated in the 'datafilepath' and
741
  'inlinedatafilepath' build properties must be writeable
742
  by user account under which Tomcat runs or you will not be able to upload
743
  data files to the system.
744
  </p>
745
746 2905 harris
  <p class="header">To install metacat LSID support, adjust the LSID-related
747
    properties in the build.properties files and type:
748
  <p class="header"><b>ant deploy-lsid</b>
749
  <p class="header">
750
  <h2>SQL Scripts</h2></p>
751 878 berkley
  <p>
752 1827 jones
   You now need to set up the table structure in your database.  You can do
753
   either do this using the ant build system, or by manually running the
754
   scripts using a sql utility.
755
  </p>
756 2182 jones
  <p><b>WARNING: Do NOT run this on an existing metacat installation as it
757
  will delete all of your data.  If you have an existing metacat installation,
758
  see the instructions for "Upgrading" below.</b></p>
759
760
  <p>To run the scripts using ant, type <code>ant installdb</code>.  This does
761
  not work for postgres, so you'll need to run the xmltables-postgres.sql script
762
  manually (see next paragraph).
763 1827 jones
  </p>
764
  <p>To run the scripts manually, change to the
765 2302 costa
   metacat/build/src directory.  Then run you RDBMS's SQL utility.  In Oracle it is
766 878 berkley
   SQLPlus.  This tutorial assumes an Oracle database so this example is for
767
   SQLPlus.  Login as the oracle user that was set up for use with Metacat.
768 1770 tao
   At the SQLPlus prompt type the following: <pre><b>@xmltables.sql;</b></pre>
769 2182 jones
   For postgres, use a command like:
770
   <code>psql -U metacat -W -h localhost -f build/src/xmltables-postgres.sql metacat</code>
771 1827 jones
  </p>
772
  <p>Either way,
773
   you should see a bunch of output showing the creation of the Metacat table
774 878 berkley
   space. The first time you run this script you will get several errors at the
775
   beginning saying that you cannot drop a table/index/trigger because it
776
   does not exist.  This is normal.  Any other errors besides this need to be
777 1770 tao
   resolved before continuing. The script file name for PostgreSQL is
778 2302 costa
   xmltables-postgres.sql and for Microsoft SQL server is
779 1827 jones
   xmltables-sqlserver.sql.
780 878 berkley
  </p>
781
  <p>
782
   If the script has run correctly you should be able to type
783 2309 jones
   <pre>describe xml_documents</pre> and it should show:
784 878 berkley
   <pre>
785
    Name            Null?         Type
786
    --------------  ------------  ----------------
787
     DOCID          NOT NULL      VARCHAR2(250)
788
     ROOTNODEID                   NUMBER(20)
789
     DOCNAME                      VARCHAR2(100)
790
     DOCTYPE                      VARCHAR2(100)
791
     DOCTITLE                     VARCHAR2(1000)
792
     USER_OWNER                   VARCHAR2(100)
793
     USER_UPDATED                 VARCHAR2(100)
794
     SERVER_LOCATION              NUMBER(20)
795
     REV                          NUMBER(10)
796
     DATE_CREATED                 DATE
797
     DATE_UPDATED                 DATE
798
     PUBLIC_ACCESS                NUMBER(1)
799
     UPDATED                      NUMBER(1)
800
   </pre>
801
  </p>
802 2322 jones
  <p class="header"><h2>Registering schemas and DTDs</h2></p>
803
  <p>Once the tables have been created, you should also register the Ecological
804
  Metadata Language (EML) DTDs and schemas. <b>However, note that you should
805
  NOT do this if you are upgrading an existing installation -- the upgrade
806
  scripts take care of it for you (see the next section).</b>  If you are
807
  installing new, you can register the schema documents by running:</p>
808
  <pre><b>ant register-schemas</b></pre>
809
  <p>This command registers the EML DTDs' and schemas' location in the
810
  metacat server.  Your database username and password have to be set correctly
811 2324 jones
  for this to work.  Also, if for some reason running this script from ant
812
  does not work, you could instead try running "build/src/loaddtdschema.sql"
813
  from your sql utility (but be sure to use the version in the 'build' directory
814
  that has been customized for your installation).
815 2322 jones
  </p>
816 1827 jones
  <p class="header"><h2>Upgrading SQL Scripts</h2></p>
817
  <p>
818
    If you have an existing metacat installation, you should not run the install
819
    script because it will replace all of the older tables with new, empty
820
    copies of the tables.  Thus you would lose your data!  Instead, you can
821
    run some upgrade scripts that will change the table structure as needed for
822
    the new version.  If you are skipping versions, run each upgrade script
823
    for the intermediate versions as well.  Currently the upgrade scripts are:
824
   </p>
825
    <ul>
826 2324 jones
      <li>build/src/upgrade-db-to-1.2.sql</li>
827
      <li>build/src/upgrade-db-to-1.3.sql</li>
828
      <li>build/src/upgrade-db-to-1.4.sql</li>
829 2501 costa
      <li>build/src/upgrade-db-to-1.5.sql</li>
830 3214 costa
      <li>build/src/upgrade-db-to-1.6.sql</li>
831
      <li>build/src/upgrade-db-to-1.7.sql</li>
832 3377 tao
      <li>build/src/upgrade-db-to-1.7.1.sql</li>
833 1827 jones
    </ul>
834
   <p>
835 3214 costa
    For example, if you had an existing metacat 1.4 installation and you were upgrading
836
    to metacat 1.7, you would need to run three scripts in sequence:
837
    upgrade-db-to-1.5.sql, upgrade-db-to-1.6.sql, and upgrade-db-to-1.7.sql.
838
    However, if you were starting from a Metacat 1.6
839
    installation, you would only need to run the upgrade-db-to-1.7.sql script.
840
    <em>Be sure to use the version of the scripts from the 'build/src' directory: they
841
    are customized for your installation in that directory.</em>
842 1827 jones
   </p>
843
  </p>
844 1770 tao
  <h2>Restart Tomcat</h2>
845 990 tao
  <p>
846 878 berkley
   Once you have successfully installed Metacat, there is one more step.  Tomcat
847
   (and Apache if you have Tomcat integrated with it) must be restarted.  To do
848 1770 tao
   this, login as the user that runs your tomcat server (often "tomcat"),
849
   go to $CATALINA_HOME/bin and type:
850 878 berkley
   <pre>
851 1770 tao
   ./shutdown.sh
852
   ./startup.sh
853 878 berkley
   </pre>
854 3545 barseghian
   In the Tomcat startup messages you should see something in the log file like:
855 878 berkley
   <pre>
856 3545 barseghian
	Metacat: [WARN]: Metacat (1.7.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]
857 878 berkley
   </pre>
858
   If you see that message Tomcat is successfully loading the Metacat servlet.
859
   Next, try to run your new servlet.  Go to a web browser and type:
860 932 jones
   <pre>http://yourserver.yourdomain.com/yourcontext/</pre>
861
   You should substitute your context name for "yourcontext" in the url above.
862 878 berkley
   If everything is working correctly, you should see a query page followed
863 880 jones
   by an empty result set.  Note that if you do not have Tomcat integrated with
864 878 berkley
   Apache you will probably have to type
865 932 jones
   <pre>http://yourserver.yourdomain.com:8080/yourcontext/</pre>
866 878 berkley
  </p>
867 3164 tao
  <p><b>Troubleshooting</b>: If you see something like java.lang.InternalError:
868
  Can't connect to X11 window server using 'yourservanme:0.0' as the value of the DISPLAY variable.
869
  <p>You should add this line:
870
  <b>JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</b> at the first line of
871 3214 costa
  catalina.sh file in tomcat bin directory. The reason is that GeoServer uses X11 windows to draw graphics.
872 3164 tao
  </p>
873 3520 tao
874
  <h2>Deploy wsdl file (Only for EarthGrid-enabled Metacat installation) </h2>
875
  <p>
876
   Once Tomcat is running successfully, there is another step for EarthGrid-enabled Metacat installation.
877
   In metacat directory, type:
878
   <pre><b>ant deploy-ecogrid</b></pre>
879
   It will generate wsdl files for EarthGrid services.
880
   </p>
881 3066 perry
882 878 berkley
</td>
883
</tr>
884
</table>
885
886
</body>
887
</html>