Project

General

Profile

metacat / docs / user / metacatinstall.html @ 4563

1
<!-- 
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: daigle $'
9
  *    '$Date: 2008-11-17 11:09:10 -0800 (Mon, 17 Nov 2008) $'
10
  *    '$Revision: 4563 $'
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="./common.css">
21
  <link rel="stylesheet" type="text/css" href="./default.css">
22
</head>
23

    
24
<body>
25

    
26
<table class="tabledefault" width="100%">
27
<tr><td rowspan="2"><img src="./images/KNBLogo.gif"></td>
28
<td colspan="7">
29
<div class="title">Metacat UNIX Installation Instructions</div>
30
</td>
31
</tr>
32
<tr>
33
  <td><a href="/" class="toollink"> KNB Home </a></td>
34
  <td><a href="/data.html" class="toollink"> Data </a></td>
35
  <td><a href="/people.html" class="toollink"> People </a></td>
36
  <td><a href="/informatics" class="toollink"> Informatics </a></td>
37
  <td><a href="/biodiversity" class="toollink"> Biocomplexity </a></td>
38
  <td><a href="/education" class="toollink"> Education </a></td>
39
  <td><a href="/software" class="toollink"> Software </a></td>
40
</tr>
41
</table>
42
<hr>
43

    
44
<div class="header1"><p class="emphasis">***Disclaimer***</p></div>
45
<p class="emphasis">
46
   These installation instructions are meant for a systems administrator/DBA
47
   or someone who is an advanced computer user.  They are NOT meant for
48
   the average computer user.  Please realize that by executing these
49
   instructions, you may have to trouble shoot many advanced issues yourself.
50
</p>
51

    
52
<div class="header1">Table of Contents</div>
53
  <div class="toc">
54
    <div class="toc1"><a href="#QuickInstructions">Quick Instructions</a></div>
55
      <div class="toc2"><a href="#QuickInstall">Quick Installation</a></div> 
56
      <div class="toc2"><a href="#QuickUpdate">Quick Update</a></div>
57
    <div class="toc1"><a href="#SourceInstall">Installing From Source Code</a></div>
58
      <div class="toc2"><a href="#WindowsXP">Windows XP</a></div>
59
      <div class="toc2"><a href="#Ubuntu8.04">Ubuntu 8.04</a></div>
60
      <div class="toc2"><a href="#MacOSX">Mac OS X</a></div>
61
    <div class="toc1"><a href="#PreInstallation">Pre-Installation</a></div>
62
      <div class="toc2"><a href="#MinRequirements">Minimum Requirements</a></div> 
63
      <div class="toc2"><a href="#AdditionalRequiredSoftware">Additional Required Software</a></div>
64
    <div class="toc1"><a href="#AdditionalSoftwareSetup">Additional Software Setup</a></div>
65
    <div class="toc1"><a href="#InstallingMetacat">Installing Metacat</a></div>
66
    <div class="toc1"><a href="#UpgradingMetacat">Upgrading Existing Metacat</a></div>
67
    <div class="toc1"><a href="#Registry">Registry</a></div>
68
  </div> 
69

    
70
<a name="QuickInstructions"></a><div class="header1">Quick Instructions</div>
71

    
72
  <a name="QuickInstall"></a><div class="header2">Quick Installation</div>  
73
  <p>These are the installation instructions for a system that has Ubuntu 8.04 installed
74
  and has never had Metacat installed on it:</p>
75
 
76
  <div class=indent>
77
    <a name="DownloadMetacatInstall"></a><div class="header3">Download Metacat Package</div>
78
    <p>Browse to the 
79
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
80
      In the Metacat section, select the link that looks like:</p>
81
          <div class="code">metacat-bin-X.X.X.tar.gz</div>
82
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally.</p>
83
    <p>Extract the Metacat package files by typing:</p>
84
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
85
    <p>You should see a war file and several supporting files.  The location where these files
86
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
87
    of this documentation.
88
  </div>
89
  
90
  <div class=indent>
91
    <a name="CreateMetacatDirs"></a><div class="header3">Create Metacat Directories</div>
92
    <p>Create the metacat utility base directory by typing:</p>
93
      <div class="code">sudo mkdir /var/metacat</div>
94
          <div class="code">sudo chown -R &lt;tomcat_user&gt; /var/metacat</div>
95
    <p>where &lt;tomcat_user&gt; is the user that will start Tomcat.  If you are 
96
        starting Tomcat as the root user, you do not need to run the chown command.</p>
97
  </div>
98

    
99
  <div class=indent>
100
    <a name="InstallJava"></a><div class="header3">Install Java</div>
101
    <p>Install Java by typing:</p>
102
      <div class="code">sudo apt-get install sun-java5-jdk</div>
103
        <p>hit "ok" then "yes" for license agreement<p>
104
  </div>
105

    
106
  <div class=indent>
107
   <a name="InstallApache"></a><div class="header3">Install Apache</div>
108
        <p>Install Apache and and Mod JK packages by typing:</p>        
109
      <div class="code">sudo apt-get install apache2</div>
110
      <div class="code">sudo apt-get install libapache2-mod-jk</div>
111
    <p>Setup Mod JK apache configuration by typing:</p>
112
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/jk.conf /etc/apache2/mods-available</div>
113
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/workers.properties /etc/apache2</div>
114
    <p>Enable Apache Mod JK by typing:</p>
115
      <div class="code">sudo a2dismod jk</div>
116
      <div class="code">sudo a2enmod jk</div>
117
    <p>Set up and enable knb (Metacat) site configurations by typing:</p>
118
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/knb /etc/apache2/sites-available</div>
119
      <div class="code">sudo a2ensite knb</div>
120
    <p>Restart apache to bring in changes by typing:</p>
121
      <div class="code">sudo /etc/init.d/apache2 force-reload</div>
122
  </div>
123
     
124
  <div class=indent> 
125
    <a name="InstallTomcat"></a><div class="header3">Install Tomcat</div>
126
    <p>Install Tomcat 5.5 by typing:</p>
127
      <div class="code">sudo sudo apt-get install tomcat5.5</div> 
128
    <p>Install Metacat friendly Tomcat startup script by typing:</p>     
129
      <div class="code">sudo /etc/init.d/tomcat5.5 stop</div>    
130
      <div class="code">sudo mv /etc/init.d/tomcat5.5 /etc/init.d/tomcat5.5.bak</div>
131
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/tomcat5.5 /etc/init.d/tomcat5.5</div>
132
      <div class="code">sudo chmod +x /etc/init.d/tomcat5.5</div>
133
    </p>
134
  </div>
135

    
136
  <div class=indent>    
137
    <a name="InstallPostgres"></a><div class="header3">Install PostgreSQL Database</div> 
138
    <p>Install PostgreSQL by typing:</p>
139
      <div class="code">sudo apt-get install postgresql</div>
140
    <p>Change to postgres user:</p>
141
      <div class="code">sudo su - postgres</div>
142
    <p>Setup empty Metacat database instance editing the postgreSQL configuration file:</p>  
143
      <div class="code">gedit /etc/postgresql/8.3/main/pg_hba.conf</div>
144
    <p>and adding the following line:</p>
145
      <div class="code">host metacat metacat 127.0.0.1 255.255.255.255 password</div>
146
    <p>Save the file, then create the metacat instance:</p>
147
      <div class="code">createdb metacat</div>
148
    <p>Log into postgreSQL by typing:</p>
149
          <div class="code">psql metacat</div>
150
        <p>and create the metacat user by typing at the psql prompt:</p>
151
          <div class="code">CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password';</div>
152
        <p>where your_password is whatever password you would like for the metacat user.</p>
153
        <p>Exit PostgreSQL by typing</p>
154
          <div class="code">\q</div>
155
        <p>Restart the PostgreSQL database to bring in changes:</p>
156
          <div class="code">/etc/init.d/postgresql-8.3 restart</div>
157
        <p>Log out of the postgres user account by typing:</p>
158
          <div class="code">logout</div>
159
        <p>Test the installation and metacat account by typing:</p>
160
          <div class="code">psql -U metacat -W -h localhost metacat</div>
161
        <p>Log back out of postgreSQL:</p>
162
          <div class="code">\q</div>
163
  </div>
164

    
165
  <div class=indent>        
166
    <a name="InstallMetacatWAR"></a><div class="header3">Install Metacat War</div> 
167
    <p>Copy the war file to Tomcat:</p>
168
          <div class="code">sudo cp knb.war /usr/share/tomcat5.5/webapps</div>
169
        <p>Restart Tomcat:</p>  
170
          <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
171
  </div>
172
        
173
  <div class=indent>        
174
    <a name="ConfigureMetacatInstall"></a><div class="header3">Configure Metacat</div> 
175
    <p>Refer to the documentation on <a href="./metacatconfigure.html">Metacat Confguration</a>
176
    to complete your installation of Metacat.</p>
177
  </div>
178
    
179
  <a name="QuickUpdate"></a><div class="header2">Quick Update</div>
180
  <p>These are the instructions for a system that already has Metacat installed on it, 
181
  but needs a Metacat upgrade:</p>
182
  
183
  <div class=indent>
184
    <a name="DownloadMetacatUpdate"></a><div class="header3">Download Metacat Package</div>
185
    <p>Browse to the 
186
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
187
      In the Metacat section, select the link that looks like:</p>
188
          <div class="code">metacat-bin-X.X.X.tar.gz</div>
189
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally.</p>
190
    <p>Extract the Metacat package files by typing:</p>
191
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
192
    <p>You should see a war file and several supporting files.  The location where these files
193
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
194
    of this documentation.
195
  </div>
196
  
197
  <div class=indent>
198
    <a name="BackupApplication"></a><div class="header3">Backup Existing Metacat Installation</div>
199
    <p>To be safe, it is best to backup the existing Metacat installation.  Do so by typing: </p>
200
          <div class="code">cp <web_app_dir>/knb <web_app_dir>/knb.bak</div>
201
          <div class="code">cp <web_app_dir>/knb.war <web_app_dir>/knb.war.bak</div>
202
        <p>Of course, you can use any backup strategy you like (or none at all).</p>
203
  </div>
204
  
205
    <div class=indent>        
206
    <a name="InstallMetacatWAR"></a><div class="header3">Install Metacat War</div> 
207
    <p>Copy the war file to Tomcat:</p>
208
          <div class="code">sudo cp knb.war /usr/share/tomcat5.5/webapps</div>
209
        <p>Restart Tomcat:</p>  
210
          <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
211
  </div>
212
        
213
  <div class=indent>        
214
    <a name="ConfigureMetacatInstall"></a><div class="header3">Configure Metacat</div> 
215
    <p>Refer to the documentation on <a href="./metacatconfigure.html">Metacat Confguration</a>
216
    to complete your installation of Metacat.</p>
217
  </div>
218

    
219
<a name="SourceInstall"></a><div class="header1">Installing From Source Code</div>
220
<p>These documents are meant to outline the metacat installation process on specific platforms. They are 
221
<strong><em>not</em></strong> a substitute for the below instructions and only meant as a supplemental guideline. </p>  
222
  <a name="WindowsXP"></a><div class="header2">Windows XP</div> 
223
    <p> See the <a href="os_specific/install_metacat_windows.html">Windows XP installation instructions</a>.</p>
224
  <a name="Ubuntu8.04"></a><div class="header2">Ubuntu 8.04</div>
225
    <p> See the <a href="os_specific/install_metacat_ubuntu.html">Ubuntu 8.04 installation instructions</a>.</p>
226
  <a name="MacOSX"></a><div class="header2">Mac OS X</div>
227
    <p> See the <a href="os_specific/install_metacat_mac.html">Mac OS X installation instructions</a>.</p>
228

    
229
<a name="PreInstallation"></a><div class="header1">Pre-Installation</div>
230
  <a name="MinRequirements"></a><div class="header2">Minimum Requirements</div> 
231
  <p>
232
   Installing Metacat requires a server running an SQL92 compliant database
233
   (Oracle 8i or Postgresql recommended) with at least 128MB RAM, and a Pentium III class
234
   processor or higher.  The amount of disk space required depends on the
235
   size of your RDBMS tablespace (which should be at least 10 MB, 
236
   however Metacat itself requires only about 1 MB of free space after 
237
   installation).  These instructions assume a Linux environment but may
238
   work on other UNIX type environments, however this has not been tested.
239
  </p>
240
  
241
  <a name="AdditionalRequiredSoftware"></a><div class="header2">Additional Required Software</div>
242
  <p>
243
   The server on which you wish to install Metacat must have the following
244
   software installed and running correctly before attempting to install
245
   Metacat.
246
   <ul>
247
     <li><a href="http://www.oracle.com">Oracle 8i</a> (or another SQL92
248
         compliant RDBMS like Postgres)</li>
249
     <li><a href="http://jakarta.apache.org/ant/index.html">Apache Jakarta-Ant</a>
250
     </li>
251
     <li><a href="http://jakarta.apache.org/tomcat/index.html">Apache Jakarta-Tomcat</a>
252
       <p class="emphasis">Note: For a more robust web serving environment, 
253
       Apache web server should
254
       be installed along with Tomcat and the two should be integrated
255
       as described on the Apache web site.</p>
256
     </li>
257
   </ul>
258
  </p>
259

    
260
<table class="tabledefault" width="100%">
261
<td class="tablehead" colspan="2"><p><a name="Additional Software Setup"><h2>Aditional Software Setup</h2></p></td>
262
<tr>
263
<td>
264
  <p class="header">Java</p>
265
  <p>You'll need a recent Java SDK; J2SE 1.4.2 or later is required.  The latest metacat release
266
  has been tested most extensively with <a href="http://java.sun.com/j2se/1.5.0/">J2SE 5.0</a>
267
  and this is the recommended version.
268
  Make sure that JAVA_HOME environment variable is properly set and that both
269
  java and javac are on your PATH.
270
  </p>
271
  <p class="header">Oracle 8i or Postgres</p>
272
  <p><i>Oracle:</i><br>
273
   The Oracle RDBMS must be installed and running as a daemon on the system.
274
   In addition the JDBC listener must be enabled.  You can enable it by
275
   logging in as your Oracle user and typing the following:
276
   <pre>lsnrctl start</pre>
277
   Your instance should have a table space of at least 5 MB (10 MB or higher 
278
   recommended).  You should also have a username specific to Metacat
279
   created and enabled.  This user must have most normal permissions 
280
   including CREATE SESSION, CREATE TABLE, CREATE INDEX, CREATE TRIGGER, 
281
   EXECUTE PROCEDURE, EXECUTE TYPE, etc.  If an action is unexplainably 
282
   rejected by Metacat it is probably because the user permissions are not
283
   correctly set.
284
  </p>
285
  <p><i>Postgres:</i><br>
286
  Postgres can be easily installed on most linux distributions and on
287
  Windows (using cygwin) and Mac OS X.  Using Fedora Core or RedHat Linux,
288
  you can install the rpms for postgres and then run 
289
  <code>/etc/init.d/postgresql start</code> in order to start the database. 
290
  On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command
291
  to install postgres: <code>sudo apt-get install postgresql-8.0</code> and 
292
  then run <code>/etc/init.d/postgresql-8.0 start</code> to start.
293
  
294
  This initializes the data files.  You need to do a bit of configuration
295
  to create a database and set up a user account and allow internet access
296
  via jdbc.  See the postgres documentation for this, but here is a quick 
297
  start:
298
  <ul>
299
     <li>Switch to the "postgres" user account and edit "data/pg_hba.conf", adding the following line to the file:<br>
300
     <code>host   metacat  metacat      127.0.0.1         255.255.255.255   password</code><br>
301
     If your host uses IPv6 addresses, you may need this line instead:
302
     <code>host   metacat  metacat      ::1               ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff password</code></li>
303
     <li>If you are using Postgresql pre-8.0, you must edit the "data/postgres.conf" file and uncomment and edit the line
304
     starting with "tcpip_socket" so that it reads 
305
     <code>tcpip_socket = true</code></li>
306
     <li>Run <code>createdb metacat</code> to create a new database</li>
307
     <li>Run <code>psql metacat</code> to log in using the postgres account and create a new "metacat" user account
308
     <ul>
309
        <li>In postgres, run <code>CREATE USER metacat WITH UNENCRYPTED PASSWORD 'apasswordyoulike';</code></li>
310
        <li>This creates a new account called metacat on the database named metacat</li>
311
        <li>Note: there are many ways to do this, so others such as using 
312
        ENCRYPTED passwords will work fine.</li>
313
     </ul>
314
     </li>
315
     <li>Exit the postgres account back to root and restart the postgres 
316
     database with <code>/etc/init.d/postgresql restart</code></li>
317
     <li>Test logging into the postgres db using the metacat account with 
318
     the following command: 
319
     <code>psql -U metacat -W -h localhost metacat</code></li>
320
  </ul>
321
  </p>
322
  <p class="header">Ant</p>
323
  <p>
324
   Ant is a Java based build application similar to Make on UNIX systems.  
325
   It takes in installation parameters from a file in the root installation
326
   directory named "build.xml".  The Metacat CVS module contains a default
327
   build.xml file that may require some modification upon installation.  Ant
328
   should be installed on the system and the "ant" executable shell script 
329
   should be available in the users path. The latest metacat release was tested with 
330
   Ant 1.6.5. <!-- We note that the current build is 
331
   not working with Ant 1.6.x, so you'll need to use an earler version.  We have 
332
   successfully used Ant 1.5.1, 1.5.2, and some earlier versions. -->
333
  </p>
334
  <p class="header">Tomcat</p>
335
  <p>
336
    Install Tomcat into the directory of your choice. The directory in which 
337
    you install Tomcat itself will be referred to as the "$CATALINA_HOME".
338
    We recommend that you install Tomcat version 5.5.  More details about 
339
    Tomcat installation are available <a href=" http://jakarta.apache.org/tomcat/index.html">here</a>.
340
  </p>
341
 </td>
342
</tr>
343
</table>
344

    
345
<table class="tabledefault" width="100%">
346
<td class="tablehead" colspan="2"><p><a name="Installing Metacat"><h2>Installing Metacat</h2></p></td>
347
<tr>
348
<td>
349
  <a name="protocol"></a>
350
  <p>This section is only for a fresh installation. If you are upgrading an existing Metacat, please skip
351
  this section and go to the next one -  <a HREF="metacatinstall.html#Upgrade">Upgrading Existing Metacat</a>
352
  
353
  <h3>Download Metacat application</h3>
354

    
355
  <p>First <a href="/software/download.html">download metacat-1.9.0.tar.gz</a> from this site.</p><br>
356

    
357
  <p>Extract the contents of the tar file in Linux/Mac by typing: </p>
358
  <pre>
359
  <b>
360
  tar-xvzf metacat-1.9.0.tar.gz
361
  </b>
362
  </pre> 
363
 
364
  <h3>Copy war file to Tomcat application directory</h3>
365

    
366
  <p>Copy knb.war to $CATALINA_HOME/webapps</p>
367
  <p>If desired, you can rename the war file to &lt;yourcontext&gt;.war</p>
368

    
369
  <h3>Create Metacat directory</h3>
370
  
371
  <p>Create the Metacat storage directory:</p>
372
  <pre>
373
  <b>
374
  mkdir /var/metacat
375
  </b>
376
  </pre> 
377
  
378
  <p>Change the ownership of the Metacat storage directory to be the user that runs Tomcat:
379
  <pre>
380
  <b>
381
  chown tomcat:tomcat /var/metacat
382
  </b>
383
  </pre></p> 
384

    
385
  <h3>Restart Tomcat</h3>
386
  <p>
387
   Once you have successfully installed Metacat, there is one more step.  Tomcat
388
   (and Apache if you have Tomcat integrated with it) must be restarted.  To do
389
   this, login as the user that runs your tomcat server (often "tomcat"),
390
   go to $CATALINA_HOME/bin and type:
391
   <pre>
392
   <b>
393
   ./shutdown.sh 
394
   ./startup.sh
395
   </b> 
396
   </pre>
397
   In the Tomcat startup messages you should see something in the log file like:
398
   <pre>
399
        Metacat: [WARN]: Metacat (1.8.1) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]
400
   </pre>
401
   If you see that message Tomcat is successfully loading the Metacat servlet.
402
   Next, try to run your new servlet.  Go to a web browser and type:
403
     <pre>
404
     http://yourserver.yourdomain.com/yourcontext/
405
     </pre>
406
   You should substitute your context name for "yourcontext" in the url above.
407
   If everything is working correctly, you should see a Metacat configuration screen.  Note that if you do not have Tomcat integrated with
408
   Apache you will probably have to type
409
     <pre>
410
     http://yourserver.yourdomain.com:8080/yourcontext/
411
     </pre>
412
  </p>
413
  <p><b>Troubleshooting</b>: If you see something like java.lang.InternalError: 
414
  Can't connect to X11 window server using 'yourservanme:0.0' as the value of the DISPLAY variable.
415
  <p>You should add this line: 
416
  <b>JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</b> at the first line of
417
  catalina.sh file in tomcat bin directory. The reason is that GeoServer uses X11 windows to draw graphics.
418
  </p>
419
  
420
  <h3>Configure Metacat</h3>
421
  <p>
422
  Once you see the Metacat configuration screen, you can follow the instructions in the 
423
  <a href="./metacatconfigure.html"> Configuring Metacat Section</a> 
424
  to complete the internal configuration of Metacat.
425
  </p>
426
  
427
  <h3>Deploy wsdl file (Only for EarthGrid-enabled Metacat installation) </h3>
428
  <p>
429
   Once Tomcat is running successfully, there is another step for EarthGrid-enabled Metacat installation. 
430
   In metacat directory, type:
431
   <pre><b>ant deploy-ecogrid</b></pre> 
432
   It will generate wsdl files for EarthGrid services.
433
   </p>
434

    
435
</td>
436
</tr>
437
</table>
438

    
439
<table class="tabledefault" width="100%">
440
<td class="tablehead" colspan="2"><p><a name="Upgrade"><h2>Compilation and Upgrading Existing Metacat</h2></p></td>
441
<tr>
442
<td>
443
  <a name="protocol"></a>
444
  <p>The following instructions are for upgrading an existing Metacat.
445
  <p><h3>Stop the running Metacat</h3>
446
   <P>To do this, login as the user that runs your tomcat server (often "tomcat"),
447
   go to $CATALINA_HOME/bin and type:
448
   <pre><b>./shutdown.sh</b> </pre>
449
  <p>    
450
  <h3>Run Ant Build</h3>
451
  <p>
452
   Ant allows compilation and upgrading to be done in one step.
453
   Change into the metacat directory and type: 
454
   <pre><b>ant clean upgrade</b></pre>
455
   <p>
456
   You should see a bunch of messages telling you the progress of compilation
457
   and installation.  When it is done you should see the message 
458
   BUILD SUCCESSFUL
459
   and you should be returned to a UNIX command prompt.  If you do not see
460
   the message BUILD SUCCESSFUL then there was an error that you need to 
461
   resolve.
462
   This may come up if you are logged in as a user that does not have write
463
   access to one or more of the directories that are listed in the build.xml
464
   file, or if any of the paths to files are not configured correctly in the
465
   "config" target.
466
  </p>
467
  <p>
468
  Note: The 'data' directories that are indicated in the 'datafilepath' and
469
  'inlinedatafilepath' build properties must be writable
470
  by user account under which Tomcat runs or you will not be able to upload 
471
  data files to the system.
472
  </p>
473

    
474
  <p class="header">To install metacat LSID support, adjust the LSID-related
475
    properties in the build.properties files and type:
476
  <p class="header"><b>ant deploy-lsid</b>
477
 
478
  <p><h3>Upgrade SQL Scripts</h3></p>
479
  <P>Note: there is no SQL script that needs to be run when user upgrades the Metacat
480
         from 1.8.0 to 1.8.1 release.</p>
481
  <p>
482
    If you have an existing metacat installation, you should not run the install
483
    script because it will replace all of the older tables with new, empty 
484
    copies of the tables.  Thus you would lose your data!  Instead, you can 
485
    run some upgrade scripts that will change the table structure as needed for
486
    the new version.  If you are skipping versions, run each upgrade script
487
    for the intermediate versions as well.  Currently the upgrade scripts are:
488
   </p>
489
    <ul>
490
      <li>build/src/upgrade-db-to-1.2.sql</li>
491
      <li>build/src/upgrade-db-to-1.3.sql</li>
492
      <li>build/src/upgrade-db-to-1.4.sql</li>
493
      <li>build/src/upgrade-db-to-1.5.sql</li>
494
      <li>build/src/upgrade-db-to-1.6.sql</li>
495
      <li>build/src/upgrade-db-to-1.7.sql</li>
496
      <li>build/src/upgrade-db-to-1.8.sql</li>
497
    </ul>
498
   <p>
499
    For example, if you had an existing metacat 1.5 installation and you were upgrading 
500
    to metacat 1.8, you would need to run three scripts in sequence:
501
    upgrade-db-to-1.6.sql, upgrade-db-to-1.7.sql, and upgrade-db-to-1.8.sql. 
502
    However, if you were starting from a Metacat 1.7
503
    installation, you would only need to run the upgrade-db-to-1.8.sql script.
504
    <em>Be sure to use the version of the scripts from the 'build/src' directory: they
505
    are customized for your installation in that directory.</em>
506
   </p>
507
   <p>
508
    Ant targets exist to do the upgrades, so you can also do the above described upgrade by running:<br />
509
   </p>
510
   <p>
511
        <strong>ant upgrade16</strong><br />
512
        <strong>ant upgrade17</strong><br />
513
        <strong>ant upgrade18</strong><br />
514
   </p>
515

    
516
  </p>
517
  <h3>Restart Tomcat</h3>
518
  <p>
519
   Once you have successfully installed Metacat, there is one more step.  Tomcat
520
   (and Apache if you have Tomcat integrated with it) must be restarted.  To do
521
   this, login as the user that runs your tomcat server (often "tomcat"),
522
   go to $CATALINA_HOME/bin and type:
523
   <pre>
524
   <b>
525
   ./startup.sh
526
   </b> 
527
   </pre>
528
   In the Tomcat startup messages you should see something in the log file like:
529
   <pre>
530
        Metacat: [WARN]: Metacat (1.8.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]
531
   </pre>
532
   If you see that message Tomcat is successfully loading the Metacat servlet.
533
   Next, try to run your new servlet.  Go to a web browser and type:
534
   <pre>http://yourserver.yourdomain.com/yourcontext/</pre>
535
   You should substitute your context name for "yourcontext" in the url above.
536
   If everything is working correctly, you should see a query page followed
537
   by an empty result set.  Note that if you do not have Tomcat integrated with
538
   Apache you will probably have to type
539
   <pre>http://yourserver.yourdomain.com:8080/yourcontext/</pre>
540
  </p>
541
  <p><b>Troubleshooting</b>: If you see something like java.lang.InternalError: 
542
  Can't connect to X11 window server using 'yourservanme:0.0' as the value of the DISPLAY variable.
543
  <p>You should add this line: 
544
  <b>JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</b> at the first line of
545
  catalina.sh file in tomcat bin directory. The reason is that GeoServer uses X11 windows to draw graphics.
546
  </p>
547
  
548
  <h3>Deploy wsdl file (Only for EarthGrid-enabled Metacat installation) </h3>
549
  <p>
550
   Once Tomcat is running successfully, there is another step for EarthGrid-enabled Metacat installation. 
551
   In metacat directory, type:
552
   <pre><b>ant deploy-ecogrid</b></pre> 
553
   It will generate wsdl files for EarthGrid services.
554
   </p>
555

    
556
</td>
557
</tr>
558
</table>
559

    
560
<table class="tabledefault" width="100%">
561
<td class="tablehead" colspan="2"><a name="Registry"><h2>Web-based Registry for Metacat</h2></td>
562
<tr>
563
<td>
564
<p>The registry allows users to upload simple metadata documents directly from the web.  See the separate 
565
<a href="registry_installation.html">Registry Installation Guide</a>.</p><br /><br />
566
</td>
567
</body>
568
</html>