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