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
   These installation instructions are meant for a systems administrator/DBA or someone
49
   who is an advanced computer user.  They are NOT meant for the average computer user.
50
   Please realize that by executing these instructions, you may have to trouble shoot
51
   many advanced issues yourself.
52
</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
         compliant RDBMS)</li>
78
     <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
       <p class="emphasis">Note: For a more robust web serving environment, Apache web server should
82
       be installed along with Tomcat and the two should be integrated
83
       as described on the Apache web site.</p>
84
     </li>
85
   </ul>
86
  </p>
87
</td>
88
</tr>
89
</table>
90
91
<table class="tabledefault" width="100%">
92
<td class="tablehead" colspan="2"><p>Aditional Software Setup</p></td>
93
<tr>
94
<td>
95
  <p class="header">Oracle 8i</p>
96
  <p>
97
   The Oracle RDBMS must be installed and running as a daemon on the system.
98
   In addition the JDBC listener must be enabled.  You can enable it by
99
   logging in as your Oracle user and typing the following:
100
   <pre>lsnrctl start</pre>
101
   Your instance should have a table space of at least 5 MB (10 MB or higher
102
   recommended).  You should also have a username specific to Metacat
103
   created and enabled.  This user must have most normal permissions
104
   including CREATE SESSION, CREATE TABLE, CREATE INDEX, CREATE TRIGGER,
105
   EXECUTE PROCEDURE, EXECUTE TYPE, etc.  If an action is unexplainably
106
   rejected by Metacat it is probably because the user permissions are not
107
   correctly set.
108
  </p>
109
  <p class="header">Ant</p>
110
  <p>
111
   Ant is a Java based build application similar to Make on UNIX systems.
112
   It takes in installation parameters from a file in the root installation
113
   directory named "build.xml".  The Metacat CVS module contains a default
114
   build.xml file that may require some modification upon installation.  Ant
115
   Should be installed on the system and the "ant" executable shell script
116
   should be available in the users path.
117
  </p>
118
  <p class="header">Tomcat</p>
119
  <p>
120
    Install tomcat into the directory of your choice. The directory in which
121
    you install Tomcat itself will be referred to as the "{Tomcat install
122
    directory}".  This install assumes Tomcat version 3.1.  The Tomcat configuration
123
    will be slightly different depending on what version of Tomcat you are running.
124
  </p>
125
  <p>
126
    You must now set up your servlet context.  Change to the {Tomcat install
127
    directory}/conf.  Edit the tomcat.conf file.  Find a line that looks like:
128
    <pre>ApJServMount /examples /root</pre>
129
    Add the following line below the aforementioned text:
130
    <pre>ApJServMount /metadata /root</pre>
131
    Save tomcat.conf.
132
  </p>
133
  <p>
134
   Edit the server.xml file.  Go to the bottom of the file.  Find the line that
135
   says:
136
   <pre>&lt;Context path="/examples" docbase="/webapps/examples" debug="0" reloadable="true" &gt;
137
   &lt;/Context&gt;</pre>
138
   Directly below these lines enter the following:
139
   <pre>&lt;Context path="/metadata" docbase="/opt/tomcat/webapps/metadata" debug="0" reloadable="true" &gt;
140
   &lt;/Context&gt;</pre>
141
   Save server.xml.
142
   <div class="emphasis">Note that capital "C" on "Context".  This MUST be a
143
   capital "C".  Also note that "metadata" is an arbitrary servlet name.  You
144
   may pick whatever servlet name you wish.</div>
145
  </p>
146
  <p>
147
   After setting up Tomcat, you must make a slight modification to the startup
148
   script.  Tomcat needs to know about special protocol handlers that Metacat
149
   uses for its URLs.  Find the line in the tomcat.sh file that says
150
   <pre>
151
    if [ "$TOMCAT_OPTS" = "" ] ; then
152
     TOMCAT_OPTS=""
153
    fi
154
   </pre>
155
   It should be on about line 65.  You need to comment out the TOMCAT_OPTS
156
   entry that is there and add the following:
157
   <pre>
158
    TOMCAT_OPTS="-Djava.protocol.handler.pkgs=edu.ucsb.nceas.protocols"
159
   </pre>
160
   When you are done the if statement should look like:
161
   <pre>
162
    if [ "$TOMCAT_OPTS" = "" ] ; then
163
     #TOMCAT_OPTS=""
164
     TOMCAT_OPTS="-Djava.protocol.handler.pkgs=edu.ucsb.nceas.protocols"
165
    fi
166
   </pre>
167
   You must also complete the <a href="#protocol">protocol.jar</a> step below
168
   for this to be completely
169
   setup.  Also, make sure that this startup script is always used to start
170
   tomcat or the parameter will not be set correctly and some features of
171
   Metacat will not work.
172
  </p>
173
  <p>
174
   Your servlet context should now be setup.  The next step is giving Tomcat
175
   something to run in that context (i.e. Metacat).
176
  </p>
177
</td>
178
</tr>
179
</table>
180
181
<table class="tabledefault" width="100%">
182
<td class="tablehead" colspan="2"><p>Configuring the Server for Metacat</p></td>
183
<tr>
184
<td>
185
  <p>
186
   Once all of the prerequisite software is installed as described above,
187
   the installation of Metacat can begin.  First you must have a current
188
   version of the source distribution of Metacat.  You can get it two ways.
189
   Authorized users can check it out of the NCEAS
190
   <a href="http://www.nceas.ucsb.edu/cgi-bin/cvsweb.cgi/xmltodb/">CVS</a>
191
   system under the module name xmltodb.  The command is as follows:
192 880 jones
   <pre>cvs checkout -P xmltodb</pre>  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
  <p>
197
   Once you have either checked out or unzipped and untarred the source
198
   distribution, you can begin the installation process.  Change into the
199
   xmltodb directory and edit the file called "build.xml".  The top of a
200
   sample build.xml file is shown below.
201
   <pre>
202
      &lt;property name="jdbc-connect" value="jdbc:oracle:thin:@dev.nceas.ucsb.edu:1521:exp"/&gt;
203 880 jones
      &lt;property name="dbDriver" value="oracle.jdbc.driver.OracleDriver"/&gt;
204 878 berkley
      &lt;property name="installdir" value="/opt/tomcat/webapps/metadata" /&gt;
205
      &lt;property name="name" value="metacat"/&gt;
206
      &lt;property name="Name" value="MetaCat"/&gt;
207 880 jones
      &lt;property name="release" value="1.0.1"/&gt;
208
      &lt;property name="web-base-url" value="http://knb.ecoinformatics.org"/&gt;
209 878 berkley
      &lt;property name="replication-path" value="/metadata/servlet/replication"/&gt;
210
      &lt;property name="servlet-path" value="/metadata/servlet/metacat"/&gt;
211
      &lt;property name="html-path" value="/metadata"/&gt;
212
      &lt;property name="image-path" value="/img/metadata" /&gt;
213 880 jones
      &lt;property name="style-path" value="/jones/style"/&gt;
214 882 jones
      &lt;property name="serverhost" value="dev.nceas.ucsb.edu"/&gt;
215
      &lt;property name="server" value="http://metacat.nceas.ucsb.edu"/&gt;
216 878 berkley
      &lt;property name="replication-log" value="metacatreplication.log"/&gt;
217
      &lt;property name="user" value="metadata"/&gt;
218
      &lt;property name="password" value="your-pw-goes-here"/&gt;
219 880 jones
      &lt;property name="config-dir" value="${installdir}" /&gt;
220
      &lt;property name="default-style" value="knb" /&gt;
221
      &lt;property name="eml-module" value="mdstandards/eml" /&gt;
222
      &lt;property name="eml-version" value="2.0.0beta6" /&gt;
223
      &lt;property name="eml-tag" value="RELEASE_EML_2_0_0_BETA_6" /&gt;
224
      &lt;property name="cvsroot"
225
               value=":ext:jones@cvs.nceas.ucsb.edu:/cvs/pbi" /&gt;
226
227
228 878 berkley
   </pre>
229
  </p>
230
  <p>
231 880 jones
   The configuration changes that you need to make are the jdbc-connect,
232
   installdir, web-base-url, replication-path, servlet-path, html-path,
233
   image-path, style-path, server, replication-log, user and password.
234
   Each is described below.
235 878 berkley
  </p>
236
  <ul>
237
  <li>
238
   The jdbc-connect parameter is the JDBC connection string needed to connect
239 880 jones
   to your database.
240 878 berkley
  </li>
241
  <li>
242 880 jones
   The dbDriver parameter is the name of the JDBC driver class to use for
243
   connections to your database.  If you are not using Oracle, you will also
244
   need to change the name of the database adapter class in the dbAdapter
245
   property in the <a href="./properties.html"?>metacat.properties</a> file.
246
  </li>
247
  <li>
248 878 berkley
   The installdir
249
   parameter is the directory that you want Ant to install the servlet to.
250
   It is your "servlet context path" that was defined above.
251
  </li>
252
  <li>
253 880 jones
   Web-base-url is the URL from which you want to load any stylesheets
254
   or supplementary images.
255 878 berkley
  </li>
256
  <li>
257 880 jones
   Replication path is the relative path to the replication servlet.  This
258 878 berkley
   should be the name of your servlet followed by "/servlet/replication".
259
  </li>
260
  <li>
261
   The servlet path is the relative path to your servlet as viewed by the
262
   Tomcat or Apache web server.  Under Tomcat, the form is usually
263
   <pre>/&lt;servlet-context-name&gt;/servlet/&lt;servlet-name&gt;</pre>
264
   In the example above "metadata" is the name of the servlet context and
265
   "metacat" is the name of the servlet.
266
  </li>
267
  <li>
268
   The html-path is usually the first directory of the servlet-path. The only
269
   reason it wouldn't be is if you are doing something with your web server
270
   and you want the html served from a different location than where the
271
   servlet is located.
272
  </li>
273
  <li>
274
   The image-path is where you want the Metacat image files stored.  It
275
   should be a directory that is accessible by the web server.
276
  </li>
277
  <li>
278 882 jones
   The serverhost is the full internet name of the server on which Metacat
279
   is running.
280 878 berkley
  </li>
281
  <li>
282 882 jones
   The server is the http address on which Metacat is running.
283
  </li>
284
  <li>
285 878 berkley
   Replication-log is the location at which you want Metacat to place any
286
   replication log files.  The user that starts Tomcat must have permission to
287
   write to this directory.
288
  </li>
289
  <li>
290 880 jones
   The user and password parmaters are the database user name that you set up
291
   to use Metacat, for example an Oracle username and password.
292 878 berkley
  </li>
293 880 jones
  <li>
294
   The config-dir parameter specifies the location of the configuration files
295
   for the "style-sets" feature.  It is set by default to the installation
296
   directory and generally does not need to be changed.
297
  </li>
298
  <li>
299
   The default-style parameter defines the "style-set" that is to be used
300
   by default when the qformat parameter is missing or set to "html" during
301
   a query.  It is set to "knb", which is the only style that ships with the
302
   default metacat distribution.  If you create your own stylesheets for
303
   displaying metacat output, you may want to create a new config file in the
304
   config-dir (e.g., mystyle.xml) and then change the default-style to use
305
   your custom style (e.g., "mystyle").
306
  </li>
307
  <li>
308
   The eml-module, eml-version, eml-tag parameters control the installation
309
   behavior with respect to EML.  You should not need to change these paramters.
310
  </li>
311
  <li>
312
   The cvsrootparameter is used when building the distribution and you should
313
   not need to change it.
314
  </li>
315 878 berkley
  </ul>
316
  <p class="emphasis">
317
   Note: DO NOT add a slash [/] to the end of these paths.  Metacat will not
318
   function correctly if you do so.
319
  </p>
320
  <p class="header">Stylesheet Scripts</p>
321
  <p>
322
   You now need to set up the table structure in your database.  Change to the
323
   xmltodb/src directory.  Then run you RDBMS's SQL utility.  In Oracle it is
324
   SQLPlus.  This tutorial assumes an Oracle database so this example is for
325
   SQLPlus.  Login as the oracle user that was set up for use with Metacat.
326
   At the SQLPlus prompt type the following: <pre>@xmltables.sql;</pre>
327
   You should see a bunch of output showing the creation of the Metacat table
328
   space. The first time you run this script you will get several errors at the
329
   beginning saying that you cannot drop a table/index/trigger because it
330
   does not exist.  This is normal.  Any other errors besides this need to be
331
   resolved before continuing.
332
  </p>
333
  <p>
334
   If the script has run correctly you should be able to type
335
   <pre>describe xml_documents</pre> and it should tell you
336
   <pre>
337
    Name            Null?         Type
338
    --------------  ------------  ----------------
339
     DOCID          NOT NULL      VARCHAR2(250)
340
     ROOTNODEID                   NUMBER(20)
341
     DOCNAME                      VARCHAR2(100)
342
     DOCTYPE                      VARCHAR2(100)
343
     DOCTITLE                     VARCHAR2(1000)
344
     USER_OWNER                   VARCHAR2(100)
345
     USER_UPDATED                 VARCHAR2(100)
346
     SERVER_LOCATION              NUMBER(20)
347
     REV                          NUMBER(10)
348
     DATE_CREATED                 DATE
349
     DATE_UPDATED                 DATE
350
     PUBLIC_ACCESS                NUMBER(1)
351
     UPDATED                      NUMBER(1)
352
   </pre>
353
  </p>
354
</td>
355
</tr>
356
</table>
357
358
<table class="tabledefault" width="100%">
359
<td class="tablehead" colspan="2"><p>Compilation and Installation</p></td>
360
<tr>
361
<td>
362
  <a name="protocol"></a>
363
  <p>
364
   Now we are ready to finish setting up Tomcat by creating the protocol.jar
365
   file.  To do this, change into the xmltodb directory and type
366
   <pre>ant protocol</pre>
367
   When it is done and says "BUILD SUCCESSFUL", change into the 'build'
368
   directory.  There will be a file there called 'protocol.jar'.  Now, copy
369
   that file to {tomcat install directory}/lib/protocol.jar.  In our case:
370
   <pre>cp protocol.jar /usr/local/devtools/jakarta-tomcat/lib/.</pre>
371
   <div class="emphasis">Note that once you have installed the protocol handlers
372
   you do not need to install them again.  You can recompile Metacat and install
373
   it without having to go through this process again.</div>
374
  </p>
375
  <p>
376
   Once the protocol.jar file is compiled and copied, you are ready to compile
377
   and install
378
   Metacat.  Ant allows compilation and installation to be done in one step.
379
   Change into the xmltodb directory and type:
380
   <pre>ant install</pre>
381
   You should see a bunch of messages telling you the progress of compilation
382
   and installation.  When it is done you should see the message BUILD SUCCESSFUL
383
   and you should be returned to a UNIX command prompt.  If you do not see
384
   the message BUILD SUCCESSFUL then there was an error that you need to resolve.
385
   This may come up if you are logged in as a user that does not have write
386
   access to one or more of the directories that are listed in the build.xml
387
   file.
388
  </p>
389 880 jones
  <p>Once metacat itself is installed, you have the option of also installing
390
  the Ecological Metadata Language (EML) DTDs. This process is done most
391
  easily by running "ant instdtd" which copies the DTDs to the installation
392
  directory, and then "ant dtdsql" which registers the DTDs with the
393
  metacat server.  Your database username and password have to be set correctly
394
  for this to work.
395 878 berkley
  <p>
396
   Once you have successfully installed Metacat, there is one more step.  Tomcat
397
   (and Apache if you have Tomcat integrated with it) must be restarted.  To do
398
   this go to {Tomcat install directory}/bin and type
399
   <pre>
400
   ./tomcat.sh stop
401
   ./tomcat.sh start
402
   </pre>
403
   In the Tomcat startup messages you should see something like:
404
   <pre>
405
    MetacatServlet Initialize
406
    Context log path="/metadata" :Metacat: init
407
    MetacatServlet Initialize
408
   </pre>
409
   If you see that message Tomcat is successfully loading the Metacat servlet.
410
   Next, try to run your new servlet.  Go to a web browser and type:
411
   <pre>http://yourserver.yourdomain.com/metadata/</pre>
412
   If everything is working correctly, you should see a query page followed
413 880 jones
   by an empty result set.  Note that if you do not have Tomcat integrated with
414 878 berkley
   Apache you will probably have to type
415
   <pre>http://yourserver.yourdomain.com:8080/metadata/</pre>
416
  </p>
417
</td>
418
</tr>
419
</table>
420
421
</body>
422
</html>