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