Project

General

Profile

metacat / docs / user / metacatinstall.html @ 4575

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-18 16:05:54 -0800 (Tue, 18 Nov 2008) $'
10
  *    '$Revision: 4575 $'
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="toc2"><a href="#AdditionalSoftwareJava">Java</a></div> 
66
      <div class="toc2"><a href="#AdditionalSoftwareOracle">Oracle</a></div>
67
      <div class="toc2"><a href="#AdditionalSoftwarePostgres">PostgreSQL</a></div>
68
      <div class="toc2"><a href="#AdditionalSoftwareAnt">Ant</a></div>
69
      <div class="toc2"><a href="#AdditionalSoftwareTomcat">Tomcat</a></div>
70
    <div class="toc1"><a href="#InstallingMetacat">Installing Metacat</a></div>
71
      <div class="toc2"><a href="#InstallDownloadMetacat">Download Metacat Application</a></div>
72
      <div class="toc2"><a href="#InstallMetacatWar">Install Metacat War</a></div>
73
      <div class="toc2"><a href="#InstallRestartTomcat">Restart Tomcat</a></div>
74
      <div class="toc2"><a href="#InstallTroubleshooting">Troubleshooting</a></div>
75
      <div class="toc2"><a href="#InstallConfigureMetacat">Configure Metacat</a></div>
76
    <div class="toc1"><a href="#UpgradingMetacat">Upgrading Existing Metacat</a></div>
77
      <div class="toc2"><a href="#UpgradeStopMetacat">Stop the Running Metacat</a></div>
78
      <div class="toc2"><a href="#UpgradeDownloadMetacat">Download Latest Metacat Application</a></div>
79
      <div class="toc2"><a href="#UpgradeMetacatWar">Upgrade Metacat War</a></div>
80
      <div class="toc2"><a href="#UpgradeRestartTomcat">Restart Tomcat</a></div>
81
      <div class="toc2"><a href="#UpgradeTroubleshooting">Troubleshooting</a></div>
82
      <div class="toc2"><a href="#UpgradeConfigureMetacat">Configure Metacat</a></div>       
83
    <div class="toc1"><a href="#Registry">Web Based Registry</a></div>
84
  </div> 
85

    
86
<a name="QuickInstructions"></a><div class="header1">Quick Instructions</div>
87

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

    
115
  <div class=indent>
116
    <a name="InstallJava"></a><div class="header3">Install Java</div>
117
    <p>Install Java by typing:</p>
118
      <div class="code">sudo apt-get install sun-java5-jdk</div>
119
        <p>hit "ok" then "yes" for license agreement<p>
120
  </div>
121

    
122
  <div class=indent>
123
   <a name="InstallApache"></a><div class="header3">Install Apache</div>
124
        <p>Install Apache and and Mod JK packages by typing:</p>        
125
      <div class="code">sudo apt-get install apache2</div>
126
      <div class="code">sudo apt-get install libapache2-mod-jk</div>
127
    <p>Setup Mod JK apache configuration by typing:</p>
128
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/jk.conf /etc/apache2/mods-available</div>
129
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/workers.properties /etc/apache2</div>
130
    <p>Enable Apache Mod JK by typing:</p>
131
      <div class="code">sudo a2dismod jk</div>
132
      <div class="code">sudo a2enmod jk</div>
133
    <p>Set up and enable knb (Metacat) site configurations by typing:</p>
134
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/knb /etc/apache2/sites-available</div>
135
      <div class="code">sudo a2ensite knb</div>
136
    <p>If you want to run an LSID server along with the Metacat server, set up and enable the authority service site 
137
      configurations by typing:</p>
138
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/authority /etc/apache2/sites-available</div>
139
      <div class="code">sudo a2ensite authority</div>
140
    <p>Restart apache to bring in changes by typing:</p>
141
      <div class="code">sudo /etc/init.d/apache2 force-reload</div>
142
  </div>
143
     
144
  <div class=indent> 
145
    <a name="InstallTomcat"></a><div class="header3">Install Tomcat</div>
146
    <p>Install Tomcat 5.5 by typing:</p>
147
      <div class="code">sudo sudo apt-get install tomcat5.5</div> 
148
    <p>Install Metacat friendly Tomcat startup script by typing:</p>     
149
      <div class="code">sudo /etc/init.d/tomcat5.5 stop</div>    
150
      <div class="code">sudo mv /etc/init.d/tomcat5.5 /etc/init.d/tomcat5.5.bak</div>
151
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/tomcat5.5 /etc/init.d/tomcat5.5</div>
152
      <div class="code">sudo chmod +x /etc/init.d/tomcat5.5</div>
153
    </p>
154
  </div>
155

    
156
  <div class=indent>    
157
    <a name="InstallPostgres"></a><div class="header3">Install PostgreSQL Database</div> 
158
    <p>Install PostgreSQL by typing:</p>
159
      <div class="code">sudo apt-get install postgresql</div>
160
    <p>Change to postgres user:</p>
161
      <div class="code">sudo su - postgres</div>
162
    <p>Setup empty Metacat database instance editing the postgreSQL configuration file:</p>  
163
      <div class="code">gedit /etc/postgresql/8.3/main/pg_hba.conf</div>
164
    <p>and adding the following line:</p>
165
      <div class="code">host metacat metacat 127.0.0.1 255.255.255.255 password</div>
166
    <p>Save the file, then create the metacat instance:</p>
167
      <div class="code">createdb metacat</div>
168
    <p>Log into postgreSQL by typing:</p>
169
          <div class="code">psql metacat</div>
170
        <p>and create the metacat user by typing at the psql prompt:</p>
171
          <div class="code">CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password';</div>
172
        <p>where your_password is whatever password you would like for the metacat user.</p>
173
        <p>Exit PostgreSQL by typing</p>
174
          <div class="code">\q</div>
175
        <p>Restart the PostgreSQL database to bring in changes:</p>
176
          <div class="code">/etc/init.d/postgresql-8.3 restart</div>
177
        <p>Log out of the postgres user account by typing:</p>
178
          <div class="code">logout</div>
179
        <p>Test the installation and metacat account by typing:</p>
180
          <div class="code">psql -U metacat -W -h localhost metacat</div>
181
        <p>Log back out of postgreSQL:</p>
182
          <div class="code">\q</div>
183
  </div>
184

    
185
  <div class=indent>        
186
    <a name="QuickInstallMetacatWar"></a><div class="header3">Install Metacat War</div> 
187
    <p>Copy the war file to Tomcat:</p>
188
          <div class="code">sudo cp &lt;metacat_package_dir&gt;/knb.war /usr/share/tomcat5.5/webapps</div>
189
        <p>Restart Tomcat:</p>  
190
          <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
191
  </div>
192
  
193
  <div class=indent>        
194
    <a name="QuickInstallLsidWar"></a><div class="header3">Install LSID War</div> 
195
    <p>If you want to run an LSID server along with the Metacat server, copy the 
196
    authority.war file to Tomcat:</p>
197
          <div class="code">sudo cp &lt;metacat_package_dir&gt;/authority.war /usr/share/tomcat5.5/webapps</div>
198
        <p>Restart Tomcat:</p>  
199
          <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
200
  </div>
201
        
202
  <div class=indent>        
203
    <a name="ConfigureMetacatInstall"></a><div class="header3">Configure Metacat</div> 
204
    <p>Refer to the documentation on <a href="./metacatconfigure.html">Metacat Confguration</a>
205
    to complete your installation of Metacat.</p>
206
  </div>
207
    
208
  <a name="QuickUpdate"></a><div class="header2">Quick Update</div>
209
  <p>These are the instructions for a system that already has Metacat installed on it, 
210
  but needs a Metacat upgrade:</p>
211
  
212
  <div class=indent>
213
    <a name="DownloadMetacatUpdate"></a><div class="header3">Download Metacat Package</div>
214
    <p>Browse to the 
215
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
216
      In the Metacat section, select the link that looks like:</p>
217
          <div class="code">metacat-bin-X.X.X.tar.gz</div>
218
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally.</p>
219
    <p>Extract the Metacat package files by typing:</p>
220
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
221
    <p>You should see a war file and several supporting files.  The location where these files
222
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
223
    of this documentation.
224
  </div>
225
  
226
  <div class=indent>
227
    <a name="BackupApplication"></a><div class="header3">Backup Existing Metacat Installation</div>
228
    <p>To be safe, it is best to backup the existing Metacat installation.  Do so by typing: </p>
229
          <div class="code">cp <web_app_dir>/knb <web_app_dir>/knb.bak</div>
230
          <div class="code">cp <web_app_dir>/knb.war <web_app_dir>/knb.war.bak</div>
231
        <p>Of course, you can use any backup strategy you like (or none at all).</p>
232
  </div>
233
  
234
    <div class=indent>        
235
    <a name="QuickUpdateMetacatWar"></a><div class="header3">Install Metacat War</div> 
236
    <p>Copy the war file to Tomcat:</p>
237
          <div class="code">sudo cp knb.war /usr/share/tomcat5.5/webapps</div>
238
        <p>Restart Tomcat:</p>  
239
          <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
240
  </div>
241
  
242
  <div class=indent>        
243
    <a name="QuickUpdateLsidWar"></a><div class="header3">Update LSID War</div> 
244
    <p>If you want to run an LSID server along with the Metacat server, copy the 
245
    authority.war file to Tomcat:</p>
246
          <div class="code">sudo cp &lt;metacat_package_dir&gt;/authority.war /usr/share/tomcat5.5/webapps</div>
247
        <p>Restart Tomcat:</p>  
248
          <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
249
  </div>
250
        
251
  <div class=indent>        
252
    <a name="ConfigureMetacatInstall"></a><div class="header3">Configure Metacat</div> 
253
    <p>Refer to the documentation on <a href="./metacatconfigure.html">Metacat Confguration</a>
254
    to complete your installation of Metacat.</p>
255
  </div>
256

    
257
<a name="SourceInstall"></a><div class="header1">Installing From Source Code</div>
258
<p>These documents are meant to outline the metacat installation process on specific platforms. They are 
259
<strong><em>not</em></strong> a substitute for the below instructions and only meant as a supplemental guideline. </p>  
260
  <a name="WindowsXP"></a><div class="header2">Windows XP</div> 
261
    <p> See the <a href="os_specific/install_metacat_windows.html">Windows XP installation instructions</a>.</p>
262
  <a name="Ubuntu8.04"></a><div class="header2">Ubuntu 8.04</div>
263
    <p> See the <a href="os_specific/install_metacat_ubuntu.html">Ubuntu 8.04 installation instructions</a>.</p>
264
  <a name="MacOSX"></a><div class="header2">Mac OS X</div>
265
    <p> See the <a href="os_specific/install_metacat_mac.html">Mac OS X installation instructions</a>.</p>
266

    
267
<a name="PreInstallation"></a><div class="header1">Pre-Installation</div>
268
  <a name="MinRequirements"></a><div class="header2">Minimum Requirements</div> 
269
  <p>
270
   Installing Metacat requires a server running an SQL92 compliant database
271
   (Oracle 8i or Postgresql recommended) with at least 128MB RAM, and a Pentium III class
272
   processor or higher.  The amount of disk space required depends on the
273
   size of your RDBMS tablespace (which should be at least 10 MB, 
274
   however Metacat itself requires only about 1 MB of free space after 
275
   installation).  These instructions assume a Linux environment but may
276
   work on other UNIX type environments, however this has not been tested.
277
  </p>
278
  
279
  <a name="AdditionalRequiredSoftware"></a><div class="header2">Additional Required Software</div>
280
  <p>
281
   The server on which you wish to install Metacat must have the following
282
   software installed and running correctly before attempting to install
283
   Metacat.
284
   <ul>
285
     <li><a href="http://www.oracle.com">Oracle 8i</a> (or another SQL92
286
         compliant RDBMS like Postgres)</li>
287
     <li><a href="http://jakarta.apache.org/ant/index.html">Apache Jakarta-Ant</a>
288
     </li>
289
     <li><a href="http://jakarta.apache.org/tomcat/index.html">Apache Jakarta-Tomcat</a>
290
       <p class="emphasis">Note: For a more robust web serving environment, 
291
       Apache web server should
292
       be installed along with Tomcat and the two should be integrated
293
       as described on the Apache web site.</p>
294
     </li>
295
   </ul>
296
  </p>
297

    
298
<a name="AdditionalSoftwareSetup"></a><div class="header1">Additional Software Setup</div>
299
  <a name="AdditionalSoftwareJava"></a><div class="header2">Java</div>
300
  <p>You'll need a recent Java SDK; J2SE 1.4.2 or later is required.  The latest metacat release
301
  has been tested most extensively with <a href="http://java.sun.com/j2se/1.5.0/">J2SE 5.0</a>
302
  and this is the recommended version.
303
  Make sure that JAVA_HOME environment variable is properly set and that both
304
  java and javac are on your PATH.
305
  </p>
306
  <a name="AdditionalSoftwareOracle"></a><div class="header2">Oracle 8i</div>
307
  <p>The Oracle RDBMS must be installed and running as a daemon on the system.
308
   In addition the JDBC listener must be enabled.  You can enable it by
309
   logging in as your Oracle user and typing the following:</p>
310
   
311
     <div class="code">lsnrctl start</div>
312
     
313
   <p>Your instance should have a table space of at least 5 MB (10 MB or higher 
314
   recommended).  You should also have a username specific to Metacat
315
   created and enabled.  This user must have most normal permissions 
316
   including CREATE SESSION, CREATE TABLE, CREATE INDEX, CREATE TRIGGER, 
317
   EXECUTE PROCEDURE, EXECUTE TYPE, etc.  If an action is unexplainably 
318
   rejected by Metacat it is probably because the user permissions are not
319
   correctly set.</p>
320
   
321
  <a name="AdditionalSoftwarePostgreSQL"></a><div class="header2">PostgreSQL</div>
322
  <p>PostgreSQL can be easily installed on most linux distributions and on
323
  Windows (using cygwin) and Mac OS X.  Using Fedora Core or RedHat Linux,
324
  you can install the rpms for postgres and then run </p>
325
  
326
    <div class="code">/etc/init.d/postgresql start</div> 
327
    
328
  <p>in order to start the database. 
329
  On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command
330
  to install postgres: <code>sudo apt-get install postgresql-8.0</code> and 
331
  then run <code>/etc/init.d/postgresql-8.0 start</code> to start.
332
  
333
  This initializes the data files.  You need to do a bit of configuration
334
  to create a database and set up a user account and allow internet access
335
  via jdbc.  See the postgres documentation for this, but here is a quick 
336
  start:
337
  <ul>
338
     <li>Switch to the "postgres" user account and edit "data/pg_hba.conf", adding the following line to the file:<br>
339
     <code>host   metacat  metacat      127.0.0.1         255.255.255.255   password</code><br>
340
     If your host uses IPv6 addresses, you may need this line instead:
341
     <code>host   metacat  metacat      ::1               ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff password</code></li>
342
     <li>If you are using Postgresql pre-8.0, you must edit the "data/postgres.conf" file and uncomment and edit the line
343
     starting with "tcpip_socket" so that it reads 
344
     <code>tcpip_socket = true</code></li>
345
     <li>Run <code>createdb metacat</code> to create a new database</li>
346
     <li>Run <code>psql metacat</code> to log in using the postgres account and create a new "metacat" user account
347
     <ul>
348
        <li>In postgres, run <code>CREATE USER metacat WITH UNENCRYPTED PASSWORD 'apasswordyoulike';</code></li>
349
        <li>This creates a new account called metacat on the database named metacat</li>
350
        <li>Note: there are many ways to do this, so others such as using 
351
        ENCRYPTED passwords will work fine.</li>
352
     </ul>
353
     </li>
354
     <li>Exit the postgres account back to root and restart the postgres 
355
     database with <code>/etc/init.d/postgresql restart</code></li>
356
     <li>Test logging into the postgres db using the metacat account with 
357
     the following command: 
358
     <code>psql -U metacat -W -h localhost metacat</code></li>
359
  </ul>
360
  </p>
361
  
362
  <a name="AdditionalSoftwareAnt"></a><div class="header2">Ant</div>
363
  <p>
364
   Ant is a Java based build application similar to Make on UNIX systems.  
365
   It takes in installation parameters from a file in the root installation
366
   directory named "build.xml".  The Metacat CVS module contains a default
367
   build.xml file that may require some modification upon installation.  Ant
368
   should be installed on the system and the "ant" executable shell script 
369
   should be available in the users path. The latest metacat release was tested with 
370
   Ant 1.6.5. <!-- We note that the current build is 
371
   not working with Ant 1.6.x, so you'll need to use an earler version.  We have 
372
   successfully used Ant 1.5.1, 1.5.2, and some earlier versions. -->
373
  </p>
374
  
375
  <a name="AdditionalSoftwareTomcat"></a><div class="header2">Tomcat</div>
376
  <p>
377
    Install Tomcat into the directory of your choice. The directory in which 
378
    you install Tomcat itself will be referred to as the "$CATALINA_HOME".
379
    We recommend that you install Tomcat version 5.5.  More details about 
380
    Tomcat installation are available <a href=" http://jakarta.apache.org/tomcat/index.html">here</a>.
381
  </p>
382

    
383
<a name="InstallingMetacat"></a><div class="header1">Installing Metacat</div>
384
  <a name="protocol"></a>
385
  <p>This section is only for a fresh installation. If you are upgrading an existing Metacat, please skip
386
  this section and go to the next one - <a href="metacatinstall.html#Upgrade">Upgrading Existing Metacat</a>
387
  
388
  <a name="InstallDownloadMetacat"></a><div class="header2">Download Metacat Application</div>
389
    <p>Browse to the 
390
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
391
      In the Metacat section, select the link that looks like:</p>
392
          <div class="code">metacat-bin-X.X.X.tar.gz</div>
393
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally.</p>
394
    <p>Extract the Metacat package files by typing:</p>
395
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
396
    <p>You should see a war file and several supporting files.  The location where these files
397
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
398
    of this documentation.
399
        
400
  <a name="InstallMetacatWar"></a><div class="header2">Install Metacat War</div> 
401
    <p>Copy the war file to Tomcat:</p>
402
          <div class="code">sudo cp knb.war /usr/share/tomcat5.5/webapps</div>
403
        <p>Restart Tomcat:</p>  
404
          <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
405

    
406
  <a name="InstallRestartTomcat"></a><div class="header2">Restart Tomcat</div>
407
  <p>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
   this, login as the user that runs your tomcat server (often "tomcat"),
410
   go to $CATALINA_HOME/bin and type: </p>
411
   
412
     <div class="code">./shutdown.sh</div>
413
     <div class="code">./startup.sh</div>
414
   
415
   <p>In the Tomcat startup messages you should see something in the log file like:</p>
416
   
417
     <div class="code">Metacat: [WARN]: Metacat (1.9.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]</div>
418

    
419
   <p>If you see that message Tomcat has successfully loaded the Metacat servlet.
420
   Next, try to run your new servlet.  Go to a web browser and type:</p>
421
   
422
     <div class="code">http://yourserver.yourdomain.com/yourcontext/</div>
423
     
424
   <p>You should substitute your context name for "yourcontext" in the url above.
425
   If everything is working correctly, you should see a Metacat configuration screen.  Note that if you do not have Tomcat integrated with
426
   Apache you will probably have to type:</p>
427
   
428
     <div class="code">http://yourserver.yourdomain.com:8080/yourcontext/</div>
429

    
430
  <a name="InstallTroubleshooting"></a><div class="header2">Troubleshooting</div>
431
  <p>If you see something like:</p>
432
  
433
    <div class="code">java.lang.InternalError: Can't connect to X11 window server using 'yourservanme:0.0' as the value of the DISPLAY variable.</div>
434
  
435
  <p>You should add this line: </p>
436
  
437
    <div class="code">JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</div> 
438
  
439
  <p>at the first line of the catalina.sh file in tomcat bin directory. The reason is that 
440
  GeoServer uses X11 windows to draw graphics.</p>
441
  
442
  <a name="InstallConfigureMetacat"></a><div class="header2">Configure Metacat</div>
443
  <p>Once you see the Metacat configuration screen, you can follow the instructions in the 
444
  <a href="./metacatconfigure.html"> Configuring Metacat Section</a> 
445
  to complete the internal configuration of Metacat.</p>
446

    
447
<a name="UpgradingMetacat"></a><div class="header1">Upgrading Existing Metacat</div>
448
  <a name="protocol"></a>
449
  <p>The following instructions are for upgrading an existing Metacat.
450
  
451
  <a name="UpgradeStopMetacat"></a><div class="header2">Stop the Running Metacat</div>
452
   <p>To do this, login as the user that runs your tomcat server (often "tomcat"),
453
   go to $CATALINA_HOME/bin and type:</p>
454
   
455
   <div class="code">./shutdown.sh</div>  
456
  
457
  <a name="UpgradeDownloadMetacat"></a><div class="header2">Download Latest Metacat Application</div>
458
    <p>Browse to the 
459
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
460
      In the Metacat section, select the link that looks like:</p>
461
          <div class="code">metacat-bin-X.X.X.tar.gz</div>
462
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally.</p>
463
    <p>Extract the Metacat package files by typing:</p>
464
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
465
    <p>You should see a war file and several supporting files.  The location where these files
466
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
467
    of this documentation.</p>
468
 
469
   <a name="UpgradeMetacatWar"></a><div class="header2">Upgrade Metacat War</div> 
470
    <p>Copy the war file to Tomcat:</p>
471
          <div class="code">sudo cp knb.war /usr/share/tomcat5.5/webapps</div>
472
        <p>Remove (or rename) the existing application directory:</p>
473
          <div class="code">sudo rm -rf /usr/share/tomcat5.5/webapps/knb</div>
474
          <p> or </p>
475
          <div class="code">sudo mv /usr/share/tomcat5.5/webapps/knb /usr/share/tomcat5.5/webapps/knb.bak</div>
476
        <p>Restart Tomcat:</p>  
477
          <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
478
 
479
  <a name="UpgradeRestartTomcat"></a><div class="header2">Restart Tomcat</div>
480
    <p>Once you have successfully installed Metacat, there is one more step.  Tomcat
481
    (and Apache if you have Tomcat integrated with it) must be restarted.  To do
482
    this, login as the user that runs your tomcat server (often "tomcat"),
483
    go to $CATALINA_HOME/bin and type: </p>
484
   
485
      <div class="code">./startup.sh</div>
486
   
487
    <p>In the Tomcat startup messages you should see something in the log file like:</p>
488
   
489
      <div class="code">Metacat: [WARN]: Metacat (1.8.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]</div>
490
     
491
    If you see that message Tomcat has successfully loaded the Metacat servlet.
492
    Next, try to run your new servlet.  Go to a web browser and type:</p>
493
   
494
      <div class="code">http://yourserver.yourdomain.com/yourcontext/</div>
495
     
496
    <p>You should substitute your context name for "yourcontext" in the url above.
497
    If everything is working correctly, you should see a query page followed
498
    by an empty result set.  Note that if you do not have Tomcat integrated with
499
    Apache you will probably have to type</p>
500
   
501
    <div class="code">http://yourserver.yourdomain.com:8080/yourcontext/</div>
502

    
503
  <a name="UpgradeTroubleshooting"></a><div class="header2">Troubleshooting</div>
504
  <p>If you see something like: 
505
  
506
    <div class="code">java.lang.InternalError: Can't connect to X11 window server using 'yourservanme:0.0' as the value of the DISPLAY variable.</div>
507
  
508
  <p>You should add this line: </p>
509
  
510
    <div class="code">JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</div> 
511
  <p>at the first line of the catalina.sh file in the tomcat bin directory. The reason is that 
512
  GeoServer uses X11 windows to draw graphics.</p>
513
  
514
  <a name="UpgradeConfigureMetacat"></a><div class="header2">Configure Metacat</div>
515
  <p>Once you see the Metacat configuration screen, you can follow the instructions in the 
516
  <a href="./metacatconfigure.html"> Configuring Metacat Section</a> 
517
  to complete the internal configuration of Metacat.</p>
518

    
519
<a name="Registry"></a><div class="header1">Web Based Registry</div>
520
  <p>The registry allows users to upload simple metadata documents directly from the web.  See the separate 
521
  <a href="registry_installation.html">Registry Installation Guide</a>.</p><br/><br/>
522
</body>
523
</html>