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 1770 tao
    you install Tomcat itself will be referred to as the "$CATALINA_HOME".
123
    We recommend to install Tomcat version 4.0.  More details about
124
    tomcat installation is avaliable in <a href=" http://jakarta.apache.org/tomcat/index.html">here</a>.
125 878 berkley
  </p>
126 1770 tao
 </td>
127 878 berkley
</tr>
128
</table>
129
130
<table class="tabledefault" width="100%">
131 1770 tao
<td class="tablehead" colspan="2"></td>
132 878 berkley
<tr>
133
<td>
134
  <p>
135
   Once all of the prerequisite software is installed as described above,
136
   the installation of Metacat can begin.  First you must have a current
137
   version of the source distribution of Metacat.  You can get it two ways.
138
   Authorized users can check it out of the NCEAS
139
   <a href="http://www.nceas.ucsb.edu/cgi-bin/cvsweb.cgi/xmltodb/">CVS</a>
140 1770 tao
   system under the module name metacat.  The command is as follows:
141
   <pre>cvs checkout -P metacat</pre>  Or you can
142 878 berkley
   <a href="@server@/software/download.html">download</a> a gzipped tar file
143
   from this site.
144
  </p>
145 1770 tao
  <p><h2>Edit build.xml File</h2></p>
146 878 berkley
  <p>
147
   Once you have either checked out or unzipped and untarred the source
148
   distribution, you can begin the installation process.  Change into the
149 1770 tao
   metacat directory and edit the file called "build.xml".  You will need
150 932 jones
   to change a number of configuration properties to match the setup on
151
   your system.  If you are using oracle, you'll need to customize the
152
   properties in the "oracle" target.  If you are using Postgres, you'll
153 989 berkley
   need to customize the properties in the "postgres" target.  All users
154 932 jones
   will need to customize the properties in the "config" target.
155 878 berkley
  </p>
156
  <p>
157 932 jones
   The properties that you need to change will include jdbc-connect,
158 988 tao
   dbDriver, dbAdapter, oracle_home,
159 989 berkley
   jdbc, tomcat, webapps, context, user, server, systemidserver,
160 988 tao
   web-base-url, and default-style. Each is described in detail below.
161
   You should also verify that the jar file properties mentioned in the
162
   remainder of the config target are accessible at the paths listed -- the
163
   defaults will usually work.
164 878 berkley
  </p>
165 989 berkley
  <p>
166
   Note that the build file is preconfigured to install Metacat either using
167
   Oracle or PostgreSQL as a backend database.  To change the database
168
   system, simply change the 'depends' attribute of the 'config' target to be
169
   the name of the database target that you wish to use (either 'oracle' or
170
   'postgresql').  If you wish to use a different database system, add a new
171
   target for your database with the needed parameters and actions then add it
172
   to the 'depends' attribute.
173
  </p>
174 932 jones
  Properties you will likely need to change:<br />
175 878 berkley
  <ul>
176
  <li>
177
   The jdbc-connect parameter is the JDBC connection string needed to connect
178 880 jones
   to your database.
179 878 berkley
  </li>
180
  <li>
181 880 jones
   The dbDriver parameter is the name of the JDBC driver class to use for
182 989 berkley
   connections to your database.
183 880 jones
  </li>
184
  <li>
185 932 jones
   The dbAdapter parameter is the name of the Metacat adapter class to be used
186
   to communicate with a particular database.
187 878 berkley
  </li>
188
  <li>
189 932 jones
   The oracle_home parameter is the location that oracle is installed on
190
   your system.
191
  </li>
192
  <li>
193
   The jdbc parameter is the location of your jdbc driver jar file.
194
  </li>
195
  <li>
196
   The tomcat parameter is the location in which tomcat is installed.
197
  </li>
198
  <li>
199
   The webapps parameter is the location in which your tomcat servlet
200
   contexts are installed.  This is typically "$TOMCAT_HOME/webapps".
201
  </li>
202
  <li>
203
   The context parameter is the name of the servlet context in which
204
   you want metacat to be installed.  This will determine the installation
205
   directory for the servlet and many of the urls that are used to
206
   access the installed Metacat server.
207
  </li>
208
  <li>
209 1770 tao
   The user and password parameters are the database user name that you set up
210
   to use Metacat, for example an Oracle username and password.
211
  </li>
212
  <li>
213
   The tomcatversion is the version of your Tomcat. You should put tomcat3 or
214
   tomcat4 here.
215
  </li>
216
  <li>
217 880 jones
   Web-base-url is the URL from which you want to load any stylesheets
218
   or supplementary images.
219 878 berkley
  </li>
220
  <li>
221 989 berkley
   Server is the http address on which Metacat is running (note that you should
222 990 tao
   not include the 'http://' in the server property).
223 932 jones
  </li>
224 988 tao
  </li>
225 932 jones
  <li>
226 988 tao
   The systemidserver is the protocol (http or https) and server location to get
227 989 berkley
   any DTDs.
228 988 tao
  </li>
229
  <li>
230 1770 tao
   The datafilepath is the directory to store the data file.
231 932 jones
  </li>
232
  <li>
233 1770 tao
   The inlinedatafilepath is the directory to store inline data (This is for EML2).
234
  </li>
235
  <li>
236 932 jones
   The default-style parameter defines the "style-set" that is to be used
237
   by default when the qformat parameter is missing or set to "html" during
238
   a query.  It is set to "knb", which is the only style that ships with the
239
   default metacat distribution.  If you create your own stylesheets for
240
   displaying metacat output, you may want to create a new config file in the
241
   config-dir (e.g., mystyle.xml) and then change the default-style to use
242
   your custom style (e.g., "mystyle").
243
  </li>
244 1770 tao
  <li>
245
   The debuglevel is the control value of debug message. Generally, it will vary
246
   from 0 to 70. In level 70, Metacat will desplay all debug messages.
247
  </li>
248
   <li>
249
   The forcereplicationwaitingtime is the waiting time for start force replication
250
   after uploading a package. Usually we use default value.
251
  </li>
252 932 jones
  </ul>
253
254
  Other properties that you can but generaly need not change:<br />
255
  <ul>
256
  <li>
257
   The installdir
258 989 berkley
   parameter is the directory in which Ant should install the servlet.
259 932 jones
   It is your "servlet context path" that was defined above.
260
  </li>
261
  <li>
262 880 jones
   Replication path is the relative path to the replication servlet.  This
263 989 berkley
   should be the name of your servlet followed by "/servlet/replication".  For
264
   example 'metacat/servlet/replication'.
265 878 berkley
  </li>
266
  <li>
267
   The servlet path is the relative path to your servlet as viewed by the
268
   Tomcat or Apache web server.  Under Tomcat, the form is usually
269 988 tao
   <pre>/&lt;servlet-context-name&gt;/servlet/metacat</pre>
270 878 berkley
  </li>
271
  <li>
272
   The html-path is usually the first directory of the servlet-path. The only
273
   reason it wouldn't be is if you are doing something with your web server
274
   and you want the html served from a different location than where the
275
   servlet is located.
276
  </li>
277
  <li>
278
   The image-path is where you want the Metacat image files stored.  It
279
   should be a directory that is accessible by the web server.
280
  </li>
281
  <li>
282
   Replication-log is the location at which you want Metacat to place any
283
   replication log files.  The user that starts Tomcat must have permission to
284
   write to this directory.
285
  </li>
286
  <li>
287 880 jones
   The config-dir parameter specifies the location of the configuration files
288
   for the "style-sets" feature.  It is set by default to the installation
289
   directory and generally does not need to be changed.
290
  </li>
291
  <li>
292
   The eml-module, eml-version, eml-tag parameters control the installation
293
   behavior with respect to EML.  You should not need to change these paramters.
294
  </li>
295
  <li>
296
   The cvsrootparameter is used when building the distribution and you should
297
   not need to change it.
298
  </li>
299 878 berkley
  </ul>
300
  <p class="emphasis">
301
   Note: DO NOT add a slash [/] to the end of these paths.  Metacat will not
302
   function correctly if you do so.
303
  </p>
304 1770 tao
  <p class="header"><h2>SQL Scripts</h2></p>
305 878 berkley
  <p>
306
   You now need to set up the table structure in your database.  Change to the
307 1770 tao
   metacat/src directory.  Then run you RDBMS's SQL utility.  In Oracle it is
308 878 berkley
   SQLPlus.  This tutorial assumes an Oracle database so this example is for
309
   SQLPlus.  Login as the oracle user that was set up for use with Metacat.
310 1770 tao
   At the SQLPlus prompt type the following: <pre><b>@xmltables.sql;</b></pre>
311 878 berkley
   You should see a bunch of output showing the creation of the Metacat table
312
   space. The first time you run this script you will get several errors at the
313
   beginning saying that you cannot drop a table/index/trigger because it
314
   does not exist.  This is normal.  Any other errors besides this need to be
315 1770 tao
   resolved before continuing. The script file name for PostgreSQL is
316
   xmltalbes_postgres.sql and for Microsoft SQL server is xmltables-sqlserver.sql.
317 878 berkley
  </p>
318
  <p>
319
   If the script has run correctly you should be able to type
320
   <pre>describe xml_documents</pre> and it should tell you
321
   <pre>
322
    Name            Null?         Type
323
    --------------  ------------  ----------------
324
     DOCID          NOT NULL      VARCHAR2(250)
325
     ROOTNODEID                   NUMBER(20)
326
     DOCNAME                      VARCHAR2(100)
327
     DOCTYPE                      VARCHAR2(100)
328
     DOCTITLE                     VARCHAR2(1000)
329
     USER_OWNER                   VARCHAR2(100)
330
     USER_UPDATED                 VARCHAR2(100)
331
     SERVER_LOCATION              NUMBER(20)
332
     REV                          NUMBER(10)
333
     DATE_CREATED                 DATE
334
     DATE_UPDATED                 DATE
335
     PUBLIC_ACCESS                NUMBER(1)
336
     UPDATED                      NUMBER(1)
337
   </pre>
338
  </p>
339
</td>
340
</tr>
341
</table>
342
343
<table class="tabledefault" width="100%">
344 1770 tao
<td class="tablehead" colspan="2"><p><h2>Compilation and Installation</h2></p></td>
345 878 berkley
<tr>
346
<td>
347
  <a name="protocol"></a>
348
  <p>
349 1627 tao
   Ant allows compilation and installation to be done in one step.
350
   Change into the metacat directory and type:
351 1770 tao
   <pre><b>ant install</b></pre>
352
   <p>
353 878 berkley
   You should see a bunch of messages telling you the progress of compilation
354 932 jones
   and installation.  When it is done you should see the message
355
   BUILD SUCCESSFUL
356 878 berkley
   and you should be returned to a UNIX command prompt.  If you do not see
357 932 jones
   the message BUILD SUCCESSFUL then there was an error that you need to
358
   resolve.
359 878 berkley
   This may come up if you are logged in as a user that does not have write
360
   access to one or more of the directories that are listed in the build.xml
361 932 jones
   file, or if any of the paths to files are not configured correctly in the
362
   "config" target.
363 878 berkley
  </p>
364 883 jones
  <p>Once metacat itself is installed, you should also register
365 1627 tao
  the Ecological Metadata Language (EML) DTDs and schemas. This process is done most
366 1770 tao
  easily by running:</p>
367
  <pre><b>ant dtdschemasql</b></pre>
368
  <p>This command registers the DTDs' and schemas' location in the
369 880 jones
  metacat server.  Your database username and password have to be set correctly
370
  for this to work.
371 990 tao
  </p>
372 878 berkley
  <p>
373 994 berkley
  Note: The 'data' directory in the installation directory must be writeable
374
  by whatever user is running Tomcat or you will not be able to upload data
375
  files to the system.
376 1770 tao
  <h2>Restart Tomcat</h2>
377 990 tao
  <p>
378 878 berkley
   Once you have successfully installed Metacat, there is one more step.  Tomcat
379
   (and Apache if you have Tomcat integrated with it) must be restarted.  To do
380 1770 tao
   this, login as the user that runs your tomcat server (often "tomcat"),
381
   go to $CATALINA_HOME/bin and type:
382 878 berkley
   <pre>
383 1770 tao
   ./shutdown.sh
384
   ./startup.sh
385 878 berkley
   </pre>
386 1770 tao
   In the Tomcat startup messages you should see something in log file like:
387 878 berkley
   <pre>
388
    MetacatServlet Initialize
389
    Context log path="/metadata" :Metacat: init
390
    MetacatServlet Initialize
391
   </pre>
392
   If you see that message Tomcat is successfully loading the Metacat servlet.
393
   Next, try to run your new servlet.  Go to a web browser and type:
394 932 jones
   <pre>http://yourserver.yourdomain.com/yourcontext/</pre>
395
   You should substitute your context name for "yourcontext" in the url above.
396 878 berkley
   If everything is working correctly, you should see a query page followed
397 880 jones
   by an empty result set.  Note that if you do not have Tomcat integrated with
398 878 berkley
   Apache you will probably have to type
399 932 jones
   <pre>http://yourserver.yourdomain.com:8080/yourcontext/</pre>
400 878 berkley
  </p>
401
</td>
402
</tr>
403
</table>
404
405
</body>
406
</html>