Project

General

Profile

« Previous | Next » 

Revision 2302

Revisions to Metacat Installation Instructions page. Most of the edits in this revision involve the build.properties file. A new HTML table was created to describe the properties and their values.

View differences:

docs/user/metacatinstall.html
94 94
<tr>
95 95
<td>
96 96
  <p class="header">Java</p>
97
  <p>You'll need a recent Java SDK, preferably j2sdk1.4.2 or later.  We haven't 
97
  <p>You'll need a recent Java SDK; j2sdk1.4.2 or later is required.  We haven't 
98 98
  tested with any of the 1.5.x versions yet, so probably best to stay with 1.4.x.
99 99
  Make sure that JAVA_HOME environment variable is properly set and that both
100 100
  java and javac are on your PATH.
......
157 157
  </p>
158 158
  <p class="header">Tomcat</p>
159 159
  <p>
160
    Install tomcat into the directory of your choice. The directory in which 
160
    Install Tomcat into the directory of your choice. The directory in which 
161 161
    you install Tomcat itself will be referred to as the "$CATALINA_HOME".
162
    We recommend to install Tomcat version 4.0.  More details about 
163
    tomcat installation is avaliable in <a href=" http://jakarta.apache.org/tomcat/index.html">here</a>.
162
    We recommend that you install Tomcat version 4.0.  More details about 
163
    Tomcat installation is available <a href=" http://jakarta.apache.org/tomcat/index.html">here</a>.
164 164
  </p>
165 165
 </td>
166 166
</tr>
......
186 186
   <a href="@server@/software/download.html">download</a> a gzipped tar file
187 187
   from this site.
188 188
  </p>
189
  <p><h2>Edit build.xml File</h2></p>
189
  <p><h2>Edit <code>build.properties</code> File</h2></p>
190 190
  <p>
191 191
   Once you have either checked out or unzipped and untarred the source
192 192
   distribution, you can begin the installation process.  Change into the 
193
   metacat directory and edit the file called "build.xml".  You will need 
193
   metacat directory and edit the file called "<code>build.properties</code>".  You will need 
194 194
   to change a number of configuration properties to match the setup on
195
   your system.  If you are using oracle, you'll need to customize the
196
   properties in the "oracle" target.  If you are using Postgres, you'll
197
   need to customize the properties in the "postgres" target.  All users
198
   will need to customize the properties in the "config" target.
195
   your system.
199 196
  </p>
200 197
  <p>
201
   The properties that you need to change will include jdbc-connect, 
202
   dbDriver, dbAdapter, oracle_home, 
203
   jdbc, tomcat, webapps, context, user, server, systemidserver, 
204
   web-base-url, and default-style. Each is described in detail below. 
205
   You should also verify that the jar file properties mentioned in the 
206
   remainder of the config target are accessible at the paths listed -- the 
207
   defaults will usually work.
198
  The properties that you will likely need to change will include 
199
  <code>tomcat</code>, <code>tomcatversion</code>, <code>webapps</code>, 
200
  <code>context</code>, <code>server</code>, <code>httpserver</code>, 
201
  <code>database</code>, <code>jdbc-connect</code>, <code>jdbc-base</code>, 
202
  <code>user</code>, <code>password</code>, <code>datafilepath</code>, 
203
  <code>inlinedatafilepath</code>, <code>cvsroot</code>, 
204
  <code>cvsroot-alternate</code>, and <code>default-style</code>. 
205
  Each is described in detail in the table below.
208 206
  </p>
207
  Properties you will likely need to change:
208
  <br><br>
209
  <table border="1">
210
    <tr>
211
      <td><b>Property</b></td>
212
      <td><b>Description</b></td>
213
      <td><b>Default value and examples of other values</b></td>
214
    </tr>
215
    <tr>
216
      <td>tomcat</td>
217
      <td>The tomcat property is the location in which tomcat is installed.</td>
218
      <td>Default:&nbsp;&nbsp;
219
          <code>/usr/local/devtools/jakarta-tomcat</code>
220
      <br><br>Example:&nbsp;&nbsp;
221
          <code>C:/Tomcat4</code></td>
222
    </tr>
223
    <tr>
224
      <td>tomcatversion</td>
225
      <td>The tomcatversion property is the version of your Tomcat. You should 
226
          put tomcat3 or tomcat4 here.</td>
227
      <td>Default:&nbsp;&nbsp;
228
          <code>tomcat4</code>
229
      <br><br>Example:&nbsp;&nbsp;
230
          <code>tomcat3</code>
231
      </td>
232
    </tr>
233
    <tr>
234
      <td>webapps</td>
235
      <td>The webapps property is the location in which your tomcat servlet 
236
          contexts are installed. This is typically "TOMCAT_HOME/webapps",
237
          where TOMCAT_HOME is the same value that you entered for the 'tomcat'
238
          property above.
239
      </td>
240
      <td>Default:&nbsp;&nbsp;
241
          <code>/var/www/org.ecoinformatics.knb</code>
242
      <br><br>Example:&nbsp;&nbsp;
243
          <code>C:/Tomcat4/webapps</code>
244
      </td>
245
    </tr>
246
    <tr>
247
      <td>context</td>
248
      <td>The context property is the name of the servlet context in which you 
249
          want Metacat to be installed. This will determine the installation 
250
          directory for the servlet and many of the URLs that are used to access
251
          the installed Metacat server.</td>
252
      <td>Default:&nbsp;&nbsp;
253
          <code>knb</code>
254
      <br><br>Example:&nbsp;&nbsp;
255
          <code>mycontext</code>
256
      </td>
257
    </tr>
258
    <tr>
259
      <td>server</td>
260
      <td>The server property is the secure HTTPS address on which Metacat is 
261
          running (note that you should not include the 'http://' in the server 
262
          property). The server setting should include the SSL port number 
263
          appended to the end if Tomcat is running stand-alone (see example).</td>
264
      <td>Default:&nbsp;&nbsp;
265
         <code>knb.ecoinformatics.org</code>
266
      <br><br>Example:&nbsp;&nbsp;
267
         <code>somehost.university.edu:8443</code>
268
      </td>
269
    </tr>
270
    <tr>
271
      <td>httpserver</td>
272
      <td>httpserver is the plain HTTP address on which Metacat is running 
273
          (note that you should not include the 'http://' in the httpserver property).
274
          The httpserver setting should include the HTTP plain port number 
275
          appended to the end if Tomcat is running stand-alone (see example).</td>
276
      <td>Default:&nbsp;&nbsp;
277
          <code>knb.ecoinformatics.org</code>
278
      <br><br>Example:&nbsp;&nbsp;
279
          <code>somehost.university.edu:8080</code>
280
      </td>
281
    </tr>
282
    <tr>
283
      <td>ldapUrl</td>
284
      <td>URL to the LDAP server</td>
285
      <td>Default:&nbsp;&nbsp;
286
          <code>ldap://ldap.ecoinformatics.org/dc=ecoinformatics,dc=org</code>
287
      </td>
288
    </tr>
289
    <tr>
290
      <td>database</td>
291
      <td>Select the database to use for metadata storage.
292
          Valid values are <code>oracle</code>, <code>postgresql</code>, or
293
          <code>sqlserver</code>.
294
      </td>
295
      <td>Default:&nbsp;&nbsp;
296
          <code>oracle</code>
297
      <br><br>Other possible values:&nbsp;&nbsp;
298
          <code>postgresql</code>&nbsp;&nbsp;
299
          <code>sqlserver</code>
300
      </td>
301
    </tr>
302
    <tr>
303
      <td>jdbc-connect</td>
304
      <td>The JDBC connection string used to connect to the database.</td>
305
      <td>Default:&nbsp;&nbsp;
306
          <code>jdbc:oracle:thin:@metacat.nceas.ucsb.edu:1521:knb</code>
307
      </td>
308
    <tr>
309
      <td>jdbc-base</td>
310
      <td>The base directory for locating JDBC jar files (not needed for postgresql).</td>
311
      <td>Default:&nbsp;&nbsp;
312
          <code>/usr/oracle/jdbc/lib</code>
313
      <br><br>Example:&nbsp;&nbsp;
314
          <code>C:/jdev10g/jdbc/lib</code><br>
315
      </td>
316
    </tr>
317
    <tr>
318
      <td>user</td>
319
      <td>The database user name that you set up to use Metacat. For example, 
320
          an Oracle username.</td>
321
      <td>Default:&nbsp;&nbsp;
322
          <code>knb</code>
323
      <br><br>Example:&nbsp;&nbsp;
324
          <code>metacatdb</code>
325
      </td>
326
    </tr>
327
    <tr>
328
      <td>password</td>
329
      <td>The database password that you set up to use Metacat.</td>
330
      <td>Default:&nbsp;&nbsp;
331
          <code>yourPasswordHere</code>
332
      <br><br>Example:&nbsp;&nbsp;
333
          <code>metacat123</code>
334
      </td>
335
    </tr>
336
    <tr>
337
      <td>datafilepath</td>
338
      <td>The datafilepath is the directory to store the data file.</td>
339
      <td>Default:&nbsp;&nbsp;
340
          <code>/var/metacat/data</code>
341
      <br><br>Example:&nbsp;&nbsp;
342
          <code>C:/Tomcat4/data/knb/data</code>
343
      </td>
344
    </tr>
345
    <tr>
346
      <td>inlinedatafilepath</td>
347
      <td>The inlinedatafilepath is the directory to store inline data.</td>
348
      <td>Default:&nbsp;&nbsp;
349
          <code>/var/metacat/inline-data</code>
350
      <br><br>Example:&nbsp;&nbsp;
351
          <code>C:/Tomcat4/data/knb/inlinedata</code>
352
      </td>
353
    </tr>
354
    <tr>
355
      <td>cvsroot</td>
356
      <td>CVS access to retrieve latest EML.</td>
357
      <td>Default:&nbsp;&nbsp;
358
          <code><pre>:ext:${env.USER}@cvs.ecoinformatics.org:/cvs</pre></code>
359
          Example:&nbsp;&nbsp;
360
          <code><pre>:ext:myaccount@cvs.ecoinformatics.org:/cvs</pre></code>
361
      </td>
362
    </tr>
363
    <tr>
364
      <td>cvsroot-alternate</td>
365
      <td>CVS access to retrieve latest conversion styles.</td>
366
      <td>Default:&nbsp;&nbsp;
367
          <code><pre>:ext:${env.USER}@cvs.nceas.ucsb.edu:/cvs/pbi</pre></code>
368
          Example:&nbsp;&nbsp;
369
          <code><pre>:ext:myaccount@cvs.nceas.ucsb.edu:/cvs/pbi</pre></code>
370
      </td>
371
    </tr>
372
    <tr>
373
      <td>default-style</td>
374
      <td>The default-style parameter defines the "style-set" that is to be used
375
          by default when the qformat parameter is missing or set to "html"
376
          during a query. It is set to "knb", which is one of the styles that 
377
          ships with the default metacat distribution. Other possible settings
378
          are shown in the examples to the right.</td>
379
      <td>Default:&nbsp;&nbsp;
380
          <code>knb</code>
381
      <br><br>Examples:&nbsp;&nbsp;
382
          <pre><code>default   esa   knb2   nceas   nrs   obfs   specnet</code></pre>
383
      </td>
384
    </tr>
385
  </table>
386
  <br>
209 387
  <p>
210 388
   Note that the build file is preconfigured to install Metacat either using 
211
   Oracle or PostgreSQL as a backend database.  To change the database
212
   system, simply change the 'depends' attribute of the 'config' target to be
213
   the name of the database target that you wish to use (either 'oracle' or 
214
   'postgresql').  If you wish to use a different database system, add a new
215
   target for your database with the needed parameters and actions then add it
216
   to the 'depends' attribute.
389
   Oracle, PostgreSQL, or Microsoft SQL Server as a backend database.  
390
   To change the database system, simply change the value of the 'database' 
391
   property to be the name of the database target that you wish to use 
392
   (either 'oracle', 'postgresql', or 'sqlserver').
217 393
  </p>
218
  Properties you will likely need to change:<br />
219
  <ul>
220
  <li>
221
   The jdbc-connect parameter is the JDBC connection string needed to connect 
222
   to your database.  
223
  </li>
224
  <li>
225
   The dbDriver parameter is the name of the JDBC driver class to use for
226
   connections to your database.
227
  </li>
228
  <li>
229
   The dbAdapter parameter is the name of the Metacat adapter class to be used
230
   to communicate with a particular database.
231
  </li>
232
  <li>
233
   The oracle_home parameter is the location that oracle is installed on 
234
   your system.
235
  </li>
236
  <li>
237
   The jdbc parameter is the location of your jdbc driver jar file.
238
  </li>
239
  <li>
240
   The tomcat parameter is the location in which tomcat is installed.
241
  </li>
242
  <li>
243
   The webapps parameter is the location in which your tomcat servlet
244
   contexts are installed.  This is typically "$TOMCAT_HOME/webapps".
245
  </li>
246
  <li>
247
   The context parameter is the name of the servlet context in which
248
   you want metacat to be installed.  This will determine the installation
249
   directory for the servlet and many of the urls that are used to
250
   access the installed Metacat server.
251
  </li>
252
  <li>
253
   The user and password parameters are the database user name that you set up
254
   to use Metacat, for example an Oracle username and password.
255
  </li>
256
  <li>
257
   The tomcatversion is the version of your Tomcat. You should put tomcat3 or
258
   tomcat4 here.
259
  </li>
260
  <li>
261
   Web-base-url is the URL from which you want to load any stylesheets 
262
   or supplementary images.
263
  </li>
264
  <li>
265
   Server is the http address on which Metacat is running (note that you should
266
   not include the 'http://' in the server property).
267
  </li>
268
  </li>
269
  <li>
270
   The systemidserver is the protocol (http or https) and server location to get 
271
   any DTDs.
272
  </li>
273
  <li>
274
   The datafilepath is the directory to store the data file.
275
  </li>
276
  <li>
277
   The inlinedatafilepath is the directory to store inline data (This is for EML2).
278
  </li>
279
  <li>
280
   The default-style parameter defines the "style-set" that is to be used
281
   by default when the qformat parameter is missing or set to "html" during
282
   a query.  It is set to "knb", which is the only style that ships with the
283
   default metacat distribution.  If you create your own stylesheets for
284
   displaying metacat output, you may want to create a new config file in the
285
   config-dir (e.g., mystyle.xml) and then change the default-style to use
286
   your custom style (e.g., "mystyle").
287
  </li>
288
  <li>
289
   The debuglevel is the control value of debug message. Generally, it will vary 
290
   from 0 to 70. In level 70, Metacat will desplay all debug messages.
291
  </li>
292
   <li>
293
   The forcereplicationwaitingtime is the waiting time for start force replication
294
   after uploading a package. Usually we use default value.
295
  </li>
296
  </ul>
297

  
298
  Other properties that you can but generaly need not change:<br />
299
  <ul>
300
  <li>
301
   The installdir
302
   parameter is the directory in which Ant should install the servlet.
303
   It is your "servlet context path" that was defined above.
304
  </li>
305
  <li>
306
   Replication path is the relative path to the replication servlet.  This
307
   should be the name of your servlet followed by "/servlet/replication".  For
308
   example 'metacat/servlet/replication'.
309
  </li>
310
  <li>
311
   The servlet path is the relative path to your servlet as viewed by the 
312
   Tomcat or Apache web server.  Under Tomcat, the form is usually
313
   <pre>/&lt;servlet-context-name&gt;/servlet/metacat</pre>
314
  </li>
315
  <li>
316
   The html-path is usually the first directory of the servlet-path. The only 
317
   reason it wouldn't be is if you are doing something with your web server
318
   and you want the html served from a different location than where the 
319
   servlet is located.
320
  </li>
321
  <li>
322
   The image-path is where you want the Metacat image files stored.  It
323
   should be a directory that is accessible by the web server.
324
  </li>
325
  <li>
326
   Replication-log is the location at which you want Metacat to place any 
327
   replication log files.  The user that starts Tomcat must have permission to
328
   write to this directory.
329
  </li>
330
  <li>
331
   The config-dir parameter specifies the location of the configuration files
332
   for the "style-sets" feature.  It is set by default to the installation
333
   directory and generally does not need to be changed.
334
  </li>
335
  <li>
336
   The eml-module, eml-version, eml-tag parameters control the installation
337
   behavior with respect to EML.  You should not need to change these paramters.
338
  </li>
339
  <li>
340
   The cvsrootparameter is used when building the distribution and you should
341
   not need to change it.
342
  </li>
343
  </ul>
394
  Other properties in <code>build.properties</code> that you can (but generally need not) change:<br />
395
  <br>
396
  <table border="1">
397
    <tr>
398
      <td><b>Property</b></td>
399
      <td><b>Description</b></td>
400
      <td><b>Default value and examples of other values</b></td>
401
    </tr>
402
    <tr>
403
      <td>inst.cgi.dir</td>
404
      <td>Installation directory for registry CGI scripts</td>
405
      <td>Default:&nbsp;&nbsp;
406
          <code>/var/www/cgi-knb</code>
407
      </td>
408
    </tr>
409
    <tr>
410
      <td>cgi-prefix</td>
411
      <td>&nbsp;</td>
412
      <td>Default:&nbsp;&nbsp;
413
          <code>http://knb.ecoinformatics.org/cgi-bin</code>
414
      </td>
415
    </tr>
416
    <tr>
417
      <td>knb-site-url</td>
418
      <td>This is the URL to the web context root for the knb site. 
419
          It is used for the qformat=knb skin only.</td>
420
      <td>Default:&nbsp;&nbsp;
421
          <code>http://knb.ecoinformatics.org</code>
422
      </td>
423
    </tr>
424
    <tr>
425
      <td>forcereplicationwaitingtime</td>
426
      <td>The waiting time before replication is forced to begin after
427
          uploading a package. The default value should usually suffice.</td>
428
      <td>Default:&nbsp;&nbsp;
429
          <code>30000</code>
430
          <code>&nbsp;</code>
431
      </td>
432
    </tr>
433
  </table>
434
  <p>
435
  Metacat has a number of additional settable properties in file
436
  <code>metacat/lib/metacat.properties</code>. Under most circumstances,
437
  you will not need to modify this file because the properties of interest
438
  to you can be controlled by editing <code>build.properties</code> as
439
  described above. To learn more about Metacat's additional properties,
440
  see <a href="./properties.html">Metacat Properties File</a>.
441
  </p>
344 442
  <p class="emphasis">
345
   Note: DO NOT add a slash [/] to the end of these paths.  Metacat will not
346
   function correctly if you do so.
443
   Note: When setting properties, DO NOT add a trailing slash [/] to the end of any paths that are specified.
444
   Metacat will not function correctly if you do so.
347 445
  </p>
348 446
  <p class="header"><h2>SQL Scripts</h2></p>
349 447
  <p>
......
360 458
  manually (see next paragraph).
361 459
  </p>
362 460
  <p>To run the scripts manually, change to the
363
   metacat/src directory.  Then run you RDBMS's SQL utility.  In Oracle it is
461
   metacat/build/src directory.  Then run you RDBMS's SQL utility.  In Oracle it is
364 462
   SQLPlus.  This tutorial assumes an Oracle database so this example is for
365 463
   SQLPlus.  Login as the oracle user that was set up for use with Metacat.
366 464
   At the SQLPlus prompt type the following: <pre><b>@xmltables.sql;</b></pre>
......
373 471
   beginning saying that you cannot drop a table/index/trigger because it 
374 472
   does not exist.  This is normal.  Any other errors besides this need to be
375 473
   resolved before continuing. The script file name for PostgreSQL is 
376
   xmltalbes_postgres.sql and for Microsoft SQL server is 
474
   xmltables-postgres.sql and for Microsoft SQL server is 
377 475
   xmltables-sqlserver.sql.
378 476
  </p>
379 477
  <p>
......
413 511
    </ul>
414 512
   <p>
415 513
    So, if you had an existing metacat 1.0 installation and you were upgrading 
416
    to 1.3, you would need to run both upgrade-db-to-1.2.sql and 
417
    upgrade-db-to-1.3.sql. Howver, if you were starting from a Metacat 1.2.x
418
    installation, you would only need to run the 1.3 upgrade script.
514
    to 1.4, you would need to run all three scripts in sequence:
515
    upgrade-db-to-1.2.sql, upgrade-db-to-1.3.sql, and upgrade-db-to-1.4.sql. 
516
    However, if you were starting from a Metacat 1.3.x
517
    installation, you would only need to run the upgrade-db-to-1.4.sql script.
419 518
   </p>
420 519
  </p>
421 520
</td>
......
432 531
   Change into the metacat directory and type: 
433 532
   <pre><b>ant geteml install</b></pre>
434 533
   or, if you are upgrading an existing installation, type:
435
   <pre><b>ant geteml upgrade</b></pre>
534
   <pre><b>ant clean geteml upgrade</b></pre>
436 535
   <p>
437 536
   You should see a bunch of messages telling you the progress of compilation
438 537
   and installation.  When it is done you should see the message 

Also available in: Unified diff