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
  *      '$Date$'
10
  *  '$Revision$'
11
  *
12
  *
13
  -->
14
15
<!DOCTYPE html PUBLIC "-//W3C//DTD html 4.0//EN">
16
<html>
17
18
<head>
19
  <title>Metacat Installation Instructions</title>
20
  <link rel="stylesheet" type="text/css" href="@docrooturl@default.css">
21
</head>
22
23
<body>
24
25
<table class="tabledefault" width="100%">
26
<tr><td rowspan="2"><img src="@docrooturl@images/KNBLogo.gif"></td>
27
<td colspan="7">
28
<div class="title">Metacat UNIX Installation Instructions</div>
29
</td>
30
</tr>
31
<tr>
32
  <td><a href="@server@/" class="toollink"> KNB Home </a></td>
33
  <td><a href="@server@/data.html" class="toollink"> Data </a></td>
34
  <td><a href="@server@/people.html" class="toollink"> People </a></td>
35
  <td><a href="@server@/informatics" class="toollink"> Informatics </a></td>
36
  <td><a href="@server@/biodiversity" class="toollink"> Biocomplexity </a></td>
37
  <td><a href="@server@/education" class="toollink"> Education </a></td>
38
  <td><a href="@server@/software" class="toollink"> Software </a></td>
39
</tr>
40
</table>
41
<hr>
42
43
<table class="tabledefault" width="100%">
44
<td class="tablehead" colspan="2"><p class="emphasis">***Disclaimer***</p></td>
45
<tr>
46
<td>
47
  <p class="emphasis">
48 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
   (Oracle 8i recommended) with at least 128MB RAM, and a Pentium III class
64
   processor or higher.  The amount of disk space required depends on the
65
   size of your RDBMS tablespace (which should be at least 10 MB,
66
   however Metacat itself requires only about 1 MB of free space after
67
   installation.  These instructions assume a Linux environment but may
68
   work on other UNIX type environments, however this has not been tested.
69
  </p>
70
  <p class = "header">Additional Required Software</p>
71
  <p>
72
   The server on which you wish to install Metacat must have the following
73
   software installed and running correctly before attempting to install
74
   Metacat.
75
   <ul>
76
     <li><a href="http://www.oracle.com">Oracle 8i</a> (or another SQL92
77 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
  <p class="header">Oracle 8i</p>
97
  <p>
98
   The Oracle RDBMS must be installed and running as a daemon on the system.
99
   In addition the JDBC listener must be enabled.  You can enable it by
100
   logging in as your Oracle user and typing the following:
101
   <pre>lsnrctl start</pre>
102
   Your instance should have a table space of at least 5 MB (10 MB or higher
103
   recommended).  You should also have a username specific to Metacat
104
   created and enabled.  This user must have most normal permissions
105
   including CREATE SESSION, CREATE TABLE, CREATE INDEX, CREATE TRIGGER,
106
   EXECUTE PROCEDURE, EXECUTE TYPE, etc.  If an action is unexplainably
107
   rejected by Metacat it is probably because the user permissions are not
108
   correctly set.
109
  </p>
110
  <p class="header">Ant</p>
111
  <p>
112
   Ant is a Java based build application similar to Make on UNIX systems.
113
   It takes in installation parameters from a file in the root installation
114
   directory named "build.xml".  The Metacat CVS module contains a default
115
   build.xml file that may require some modification upon installation.  Ant
116 932 jones
   should be installed on the system and the "ant" executable shell script
117 878 berkley
   should be available in the users path.
118
  </p>
119
  <p class="header">Tomcat</p>
120
  <p>
121
    Install tomcat into the directory of your choice. The directory in which
122 932 jones
    you install Tomcat itself will be referred to as the "$TOMCAT_HOME".
123
    This install assumes Tomcat version 3.1.  The Tomcat
124
    configuration will be slightly different depending on what version of
125
    Tomcat you are running.
126 878 berkley
  </p>
127
  <p>
128 932 jones
    You must now set up your servlet context.  Change to the $TOMCAT_HOME/conf.
129
    Edit the tomcat.conf file.  Find a line that looks like:
130 878 berkley
    <pre>ApJServMount /examples /root</pre>
131
    Add the following line below the aforementioned text:
132
    <pre>ApJServMount /metadata /root</pre>
133
    Save tomcat.conf.
134
  </p>
135
  <p>
136
   Edit the server.xml file.  Go to the bottom of the file.  Find the line that
137
   says:
138
   <pre>&lt;Context path="/examples" docbase="/webapps/examples" debug="0" reloadable="true" &gt;
139
   &lt;/Context&gt;</pre>
140
   Directly below these lines enter the following:
141
   <pre>&lt;Context path="/metadata" docbase="/opt/tomcat/webapps/metadata" debug="0" reloadable="true" &gt;
142
   &lt;/Context&gt;</pre>
143
   Save server.xml.
144
   <div class="emphasis">Note that capital "C" on "Context".  This MUST be a
145
   capital "C".  Also note that "metadata" is an arbitrary servlet name.  You
146 932 jones
   may pick whatever servlet name you wish. Also note that the path to the
147
   servlet context will depend on where you install the tomcat webapps
148
   directory.</div>
149 878 berkley
  </p>
150
  <p>
151
   After setting up Tomcat, you must make a slight modification to the startup
152
   script.  Tomcat needs to know about special protocol handlers that Metacat
153
   uses for its URLs.  Find the line in the tomcat.sh file that says
154
   <pre>
155
    if [ "$TOMCAT_OPTS" = "" ] ; then
156
     TOMCAT_OPTS=""
157
    fi
158
   </pre>
159
   It should be on about line 65.  You need to comment out the TOMCAT_OPTS
160
   entry that is there and add the following:
161
   <pre>
162
    TOMCAT_OPTS="-Djava.protocol.handler.pkgs=edu.ucsb.nceas.protocols"
163
   </pre>
164
   When you are done the if statement should look like:
165
   <pre>
166
    if [ "$TOMCAT_OPTS" = "" ] ; then
167
     #TOMCAT_OPTS=""
168
     TOMCAT_OPTS="-Djava.protocol.handler.pkgs=edu.ucsb.nceas.protocols"
169
    fi
170
   </pre>
171
   You must also complete the <a href="#protocol">protocol.jar</a> step below
172
   for this to be completely
173
   setup.  Also, make sure that this startup script is always used to start
174
   tomcat or the parameter will not be set correctly and some features of
175
   Metacat will not work.
176
  </p>
177
  <p>
178
   Your servlet context should now be setup.  The next step is giving Tomcat
179
   something to run in that context (i.e. Metacat).
180
  </p>
181
</td>
182
</tr>
183
</table>
184
185
<table class="tabledefault" width="100%">
186
<td class="tablehead" colspan="2"><p>Configuring the Server for Metacat</p></td>
187
<tr>
188
<td>
189
  <p>
190
   Once all of the prerequisite software is installed as described above,
191
   the installation of Metacat can begin.  First you must have a current
192
   version of the source distribution of Metacat.  You can get it two ways.
193
   Authorized users can check it out of the NCEAS
194
   <a href="http://www.nceas.ucsb.edu/cgi-bin/cvsweb.cgi/xmltodb/">CVS</a>
195
   system under the module name xmltodb.  The command is as follows:
196 880 jones
   <pre>cvs checkout -P xmltodb</pre>  Or you can
197 878 berkley
   <a href="@server@/software/download.html">download</a> a gzipped tar file
198
   from this site.
199
  </p>
200
  <p>
201
   Once you have either checked out or unzipped and untarred the source
202
   distribution, you can begin the installation process.  Change into the
203 932 jones
   xmltodb directory and edit the file called "build.xml".  You will need
204
   to change a number of configuration properties to match the setup on
205
   your system.  If you are using oracle, you'll need to customize the
206
   properties in the "oracle" target.  If you are using Postgres, you'll
207
   need to customize the properties inthe "postgres" target.  All users
208
   will need to customize the properties in the "config" target.
209 878 berkley
  </p>
210
  <p>
211 932 jones
   The properties that you need to change will include jdbc-connect,
212
   dbDriver, dbAdapter, oracle_home, jdbc, tomcat, webapps, context,
213
   user, password, server, web-base-url, and default-style.
214
   Each is described in detail below. You should also verify that the
215
   jar file properties mentioned in the remainder of the config target are
216
   accessible at the paths listed -- the defaults will usually work.
217 878 berkley
  </p>
218 932 jones
  Properties you will likely need to change:<br />
219 878 berkley
  <ul>
220
  <li>
221
   The jdbc-connect parameter is the JDBC connection string needed to connect
222 880 jones
   to your database.
223 878 berkley
  </li>
224
  <li>
225 880 jones
   The dbDriver parameter is the name of the JDBC driver class to use for
226
   connections to your database.  If you are not using Oracle, you will also
227
   need to change the name of the database adapter class in the dbAdapter
228
   property in the <a href="./properties.html"?>metacat.properties</a> file.
229
  </li>
230
  <li>
231 932 jones
   The dbAdapter parameter is the name of the Metacat adapter class to be used
232
   to communicate with a particular database.
233
   If you are not using Oracle, you will need to change this.  There are
234
   currently adapters for Oracle, Postgres, and MS SQL Server.
235 878 berkley
  </li>
236
  <li>
237 932 jones
   The oracle_home parameter is the location that oracle is installed on
238
   your system.
239
  </li>
240
  <li>
241
   The jdbc parameter is the location of your jdbc driver jar file.
242
  </li>
243
  <li>
244
   The tomcat parameter is the location in which tomcat is installed.
245
  </li>
246
  <li>
247
   The webapps parameter is the location in which your tomcat servlet
248
   contexts are installed.  This is typically "$TOMCAT_HOME/webapps".
249
  </li>
250
  <li>
251
   The context parameter is the name of the servlet context in which
252
   you want metacat to be installed.  This will determine the installation
253
   directory for the servlet and many of the urls that are used to
254
   access the installed Metacat server.
255
  </li>
256
  <li>
257 880 jones
   Web-base-url is the URL from which you want to load any stylesheets
258
   or supplementary images.
259 878 berkley
  </li>
260
  <li>
261 932 jones
   The server is the http address on which Metacat is running.
262
  </li>
263
  <li>
264
   The user and password parmaters are the database user name that you set up
265
   to use Metacat, for example an Oracle username and password.
266
  </li>
267
  <li>
268
   The default-style parameter defines the "style-set" that is to be used
269
   by default when the qformat parameter is missing or set to "html" during
270
   a query.  It is set to "knb", which is the only style that ships with the
271
   default metacat distribution.  If you create your own stylesheets for
272
   displaying metacat output, you may want to create a new config file in the
273
   config-dir (e.g., mystyle.xml) and then change the default-style to use
274
   your custom style (e.g., "mystyle").
275
  </li>
276
  </ul>
277
278
  Other properties that you can but generaly need not change:<br />
279
  <ul>
280
  <li>
281
   The installdir
282
   parameter is the directory that you want Ant to install the servlet to.
283
   It is your "servlet context path" that was defined above.
284
  </li>
285
  <li>
286 880 jones
   Replication path is the relative path to the replication servlet.  This
287 878 berkley
   should be the name of your servlet followed by "/servlet/replication".
288
  </li>
289
  <li>
290
   The servlet path is the relative path to your servlet as viewed by the
291
   Tomcat or Apache web server.  Under Tomcat, the form is usually
292
   <pre>/&lt;servlet-context-name&gt;/servlet/&lt;servlet-name&gt;</pre>
293
   In the example above "metadata" is the name of the servlet context and
294
   "metacat" is the name of the servlet.
295
  </li>
296
  <li>
297
   The html-path is usually the first directory of the servlet-path. The only
298
   reason it wouldn't be is if you are doing something with your web server
299
   and you want the html served from a different location than where the
300
   servlet is located.
301
  </li>
302
  <li>
303
   The image-path is where you want the Metacat image files stored.  It
304
   should be a directory that is accessible by the web server.
305
  </li>
306
  <li>
307
   Replication-log is the location at which you want Metacat to place any
308
   replication log files.  The user that starts Tomcat must have permission to
309
   write to this directory.
310
  </li>
311
  <li>
312 880 jones
   The config-dir parameter specifies the location of the configuration files
313
   for the "style-sets" feature.  It is set by default to the installation
314
   directory and generally does not need to be changed.
315
  </li>
316
  <li>
317
   The eml-module, eml-version, eml-tag parameters control the installation
318
   behavior with respect to EML.  You should not need to change these paramters.
319
  </li>
320
  <li>
321
   The cvsrootparameter is used when building the distribution and you should
322
   not need to change it.
323
  </li>
324 878 berkley
  </ul>
325
  <p class="emphasis">
326
   Note: DO NOT add a slash [/] to the end of these paths.  Metacat will not
327
   function correctly if you do so.
328
  </p>
329
  <p class="header">Stylesheet Scripts</p>
330
  <p>
331
   You now need to set up the table structure in your database.  Change to the
332
   xmltodb/src directory.  Then run you RDBMS's SQL utility.  In Oracle it is
333
   SQLPlus.  This tutorial assumes an Oracle database so this example is for
334
   SQLPlus.  Login as the oracle user that was set up for use with Metacat.
335 932 jones
   At the SQLPlus prompt type the following: <pre>@src/xmltables.sql;</pre>
336 878 berkley
   You should see a bunch of output showing the creation of the Metacat table
337
   space. The first time you run this script you will get several errors at the
338
   beginning saying that you cannot drop a table/index/trigger because it
339
   does not exist.  This is normal.  Any other errors besides this need to be
340
   resolved before continuing.
341
  </p>
342
  <p>
343
   If the script has run correctly you should be able to type
344
   <pre>describe xml_documents</pre> and it should tell you
345
   <pre>
346
    Name            Null?         Type
347
    --------------  ------------  ----------------
348
     DOCID          NOT NULL      VARCHAR2(250)
349
     ROOTNODEID                   NUMBER(20)
350
     DOCNAME                      VARCHAR2(100)
351
     DOCTYPE                      VARCHAR2(100)
352
     DOCTITLE                     VARCHAR2(1000)
353
     USER_OWNER                   VARCHAR2(100)
354
     USER_UPDATED                 VARCHAR2(100)
355
     SERVER_LOCATION              NUMBER(20)
356
     REV                          NUMBER(10)
357
     DATE_CREATED                 DATE
358
     DATE_UPDATED                 DATE
359
     PUBLIC_ACCESS                NUMBER(1)
360
     UPDATED                      NUMBER(1)
361
   </pre>
362
  </p>
363
</td>
364
</tr>
365
</table>
366
367
<table class="tabledefault" width="100%">
368
<td class="tablehead" colspan="2"><p>Compilation and Installation</p></td>
369
<tr>
370
<td>
371
  <a name="protocol"></a>
372
  <p>
373
   Now we are ready to finish setting up Tomcat by creating the protocol.jar
374
   file.  To do this, change into the xmltodb directory and type
375
   <pre>ant protocol</pre>
376
   When it is done and says "BUILD SUCCESSFUL", change into the 'build'
377
   directory.  There will be a file there called 'protocol.jar'.  Now, copy
378 932 jones
   that file to $TOMCAT_HOME/lib/protocol.jar.  In our case:
379 878 berkley
   <pre>cp protocol.jar /usr/local/devtools/jakarta-tomcat/lib/.</pre>
380
   <div class="emphasis">Note that once you have installed the protocol handlers
381
   you do not need to install them again.  You can recompile Metacat and install
382
   it without having to go through this process again.</div>
383
  </p>
384
  <p>
385
   Once the protocol.jar file is compiled and copied, you are ready to compile
386
   and install
387
   Metacat.  Ant allows compilation and installation to be done in one step.
388
   Change into the xmltodb directory and type:
389
   <pre>ant install</pre>
390
   You should see a bunch of messages telling you the progress of compilation
391 932 jones
   and installation.  When it is done you should see the message
392
   BUILD SUCCESSFUL
393 878 berkley
   and you should be returned to a UNIX command prompt.  If you do not see
394 932 jones
   the message BUILD SUCCESSFUL then there was an error that you need to
395
   resolve.
396 878 berkley
   This may come up if you are logged in as a user that does not have write
397
   access to one or more of the directories that are listed in the build.xml
398 932 jones
   file, or if any of the paths to files are not configured correctly in the
399
   "config" target.
400 878 berkley
  </p>
401 883 jones
  <p>Once metacat itself is installed, you should also register
402 880 jones
  the Ecological Metadata Language (EML) DTDs. This process is done most
403 883 jones
  easily by running "ant dtdsql" which registers the DTDs with the
404 880 jones
  metacat server.  Your database username and password have to be set correctly
405
  for this to work.
406 878 berkley
  <p>
407
   Once you have successfully installed Metacat, there is one more step.  Tomcat
408
   (and Apache if you have Tomcat integrated with it) must be restarted.  To do
409 932 jones
   this, login as the user that runs your tomcat server (ofter "tomcat"),
410
   go to $TOMCAT_HOME/bin and type:
411 878 berkley
   <pre>
412
   ./tomcat.sh stop
413
   ./tomcat.sh start
414
   </pre>
415
   In the Tomcat startup messages you should see something like:
416
   <pre>
417
    MetacatServlet Initialize
418
    Context log path="/metadata" :Metacat: init
419
    MetacatServlet Initialize
420
   </pre>
421
   If you see that message Tomcat is successfully loading the Metacat servlet.
422
   Next, try to run your new servlet.  Go to a web browser and type:
423 932 jones
   <pre>http://yourserver.yourdomain.com/yourcontext/</pre>
424
   You should substitute your context name for "yourcontext" in the url above.
425 878 berkley
   If everything is working correctly, you should see a query page followed
426 880 jones
   by an empty result set.  Note that if you do not have Tomcat integrated with
427 878 berkley
   Apache you will probably have to type
428 932 jones
   <pre>http://yourserver.yourdomain.com:8080/yourcontext/</pre>
429 878 berkley
  </p>
430
</td>
431
</tr>
432
</table>
433
434
</body>
435
</html>