Project

General

Profile

« Previous | Next » 

Revision 4637

Added by daigle over 15 years ago

Update installation docs for war install

View differences:

docs/user/metacatinstall.html
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$'
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="./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">Table of Contents</div>
45
  <div class="toc">
46
    <div class="toc1"><a href="#QuickInstructions">Quick Instructions</a></div>
47
      <div class="toc2"><a href="#QuickInstall">Quick Installation</a></div> 
48
      <div class="toc2"><a href="#QuickUpdate">Quick Update</a></div>
49
    <div class="toc1"><a href="#SourceInstall">Installing From Source Code</a></div>
50
      <div class="toc2"><a href="#WindowsXP">Windows XP</a></div>
51
      <div class="toc2"><a href="#Ubuntu8.04">Ubuntu 8.04</a></div>
52
      <div class="toc2"><a href="#MacOSX">Mac OS X</a></div>
53
    <div class="toc1"><a href="#PreInstallation">Pre-Installation</a></div>
54
      <div class="toc2"><a href="#MinRequirements">Minimum Requirements</a></div> 
55
      <div class="toc2"><a href="#AdditionalRequiredSoftware">Additional Required Software</a></div>
56
    <div class="toc1"><a href="#AdditionalSoftwareSetup">Additional Software Setup</a></div>
57
      <div class="toc2"><a href="#AdditionalSoftwareJava">Java</a></div> 
58
      <div class="toc2"><a href="#AdditionalSoftwareOracle">Oracle</a></div>
59
      <div class="toc2"><a href="#AdditionalSoftwarePostgres">PostgreSQL</a></div>
60
      <div class="toc2"><a href="#AdditionalSoftwareAnt">Ant</a></div>
61
      <div class="toc2"><a href="#AdditionalSoftwareTomcat">Tomcat</a></div>
62
    <div class="toc1"><a href="#InstallingMetacat">Installing Metacat</a></div>
63
      <div class="toc2"><a href="#InstallDownloadMetacat">Download Metacat Application</a></div>
64
      <div class="toc2"><a href="#InstallMetacatWar">Install Metacat War</a></div>
65
      <div class="toc2"><a href="#InstallRestartTomcat">Restart Tomcat</a></div>
66
      <div class="toc2"><a href="#InstallTroubleshooting">Troubleshooting</a></div>
67
      <div class="toc2"><a href="#InstallConfigureMetacat">Configure Metacat</a></div>
68
    <div class="toc1"><a href="#UpgradingMetacat">Upgrading Existing Metacat</a></div>
69
      <div class="toc2"><a href="#UpgradeStopMetacat">Stop the Running Metacat</a></div>
70
      <div class="toc2"><a href="#UpgradeDownloadMetacat">Download Latest Metacat Application</a></div>
71
      <div class="toc2"><a href="#UpgradeMetacatWar">Upgrade Metacat War</a></div>
72
      <div class="toc2"><a href="#UpgradeRestartTomcat">Restart Tomcat</a></div>
73
      <div class="toc2"><a href="#UpgradeTroubleshooting">Troubleshooting</a></div>
74
      <div class="toc2"><a href="#UpgradeConfigureMetacat">Configure Metacat</a></div>       
75
    <div class="toc1"><a href="#Registry">Web Based Registry</a></div>
76
    <div class="toc1"><a href="#VersionNotes">Version Installation Notes</a></div>
77
      <div class="toc2"><a href="#1_9InstallNotes">1.9 Installation Notes</a></div> 
78
  </div> 
79

  
80
<a name="QuickInstructions"></a><div class="header1">Quick Instructions</div>
81

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

  
109
  <div class=indent>
110
    <a name="InstallJava"></a><div class="header3">Install Java</div>
111
    <p>Install Java by typing:</p>
112
      <div class="code">sudo apt-get install sun-java5-jdk</div>
113
	<p>hit "ok" then "yes" for license agreement<p>
114
  </div>
115

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

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

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

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

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

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

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

  
399
  <a name="InstallRestartTomcat"></a><div class="header2">Restart Tomcat</div>
400
  <p>Once you have successfully installed Metacat, there is one more step.  Tomcat
401
   (and Apache if you have Tomcat integrated with it) must be restarted.  To do
402
   this, login as the user that runs your tomcat server (often "tomcat"),
403
   go to $CATALINA_HOME/bin and type: </p>
404
   
405
     <div class="code">./shutdown.sh</div>
406
     <div class="code">./startup.sh</div>
407
   
408
   <p>In the Tomcat startup messages you should see something in the log file like:</p>
409
   
410
     <div class="code">Metacat: [WARN]: Metacat (1.9.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]</div>
411

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

  
423
  <a name="InstallTroubleshooting"></a><div class="header2">Troubleshooting</div>
424
  <p>If you see something like:</p>
425
  
426
    <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>
427
  
428
  <p>You should add this line: </p>
429
  
430
    <div class="code">JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</div> 
431
  
432
  <p>at the first line of the catalina.sh file in tomcat bin directory. The reason is that 
433
  GeoServer uses X11 windows to draw graphics.</p>
434
  
435
  <a name="InstallConfigureMetacat"></a><div class="header2">Configure Metacat</div>
436
  <p>Once you see the Metacat configuration screen, you can follow the instructions in the 
437
  <a href="./metacatconfigure.html"> Configuring Metacat Section</a> 
438
  to complete the internal configuration of Metacat.</p>
439

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

  
496
  <a name="UpgradeTroubleshooting"></a><div class="header2">Troubleshooting</div>
497
  <p>If you see something like: 
498
  
499
    <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>
500
  
501
  <p>You should add this line: </p>
502
  
503
    <div class="code">JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</div> 
504
  <p>at the first line of the catalina.sh file in the tomcat bin directory. The reason is that 
505
  GeoServer uses X11 windows to draw graphics.</p>
506
  
507
  <a name="UpgradeConfigureMetacat"></a><div class="header2">Configure Metacat</div>
508
  <p>Once you see the Metacat configuration screen, you can follow the instructions in the 
509
  <a href="./metacatconfigure.html"> Configuring Metacat Section</a> 
510
  to complete the internal configuration of Metacat.</p>
511

  
512
<a name="Registry"></a><div class="header1">Web Based Registry</div>
513
  <p>The registry allows users to upload simple metadata documents directly from the web.  See the separate 
514
  <a href="registry_installation.html">Registry Installation Guide</a>.</p><br/><br/>
515
</body>
516
</html>
517 0

  
docs/dev/building-metacat.html
48 48
  but a few convenience options have been added to help the developer. </p>  
49 49
  
50 50
  <p>These instructions are meant to augment the Install Metacat War section of the
51
  <a href="../user/metacatinstall.html">Metacat Installation Guide</a>.</p>
51
  <a href="../user/metacat-install.html">Metacat Installation Guide</a>.</p>
52 52
  
53 53
  <p>Metacat is built using the Ant build utility.  You will need to have Ant
54 54
  installed on your development system to build Metacat</p>
......
114 114
  <a name="ManualBuild"></a><div class="header1">Manual Build</div>  
115 115
  <p>You can also build the Metacat war file and deploy manually.  To build and create the 
116 116
  war, run:</p>
117
  <div class="code">ant install-ecogrid</div> 
117
  <div class="code">ant build-metacat</div> 
118 118
  <p>The war file will appear in your &gt;metacat_workspace&lt;/dist directory.  Copy the war
119 119
  file into your tomcat webapps directory.  Delete the existing code that was expanded
120 120
  from the old jar.</p>
docs/user/properties.html
1589 1589
    </tr>
1590 1590
    <tr>
1591 1591
      <td>indexPaths</td>
1592
      <td>See <a href="./metacatinstall.html#buildProperties">description of build properties</a></td>
1592
      <td>See <a href="./metacat-install.html#buildProperties">description of build properties</a></td>
1593 1593
      <td>Default:&nbsp;&nbsp;<code>organizationName,originator/individualName/surName,...</code></td>
1594 1594
    </tr>
1595 1595
    <tr>
docs/user/metacat-install.html
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$'
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="./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">Table of Contents</div>
45
  <div class="toc">
46
    <div class="toc1"><a href="#QuickInstructions">Quick Instructions</a></div>
47
      <div class="toc2"><a href="#QuickInstall">Quick Installation</a></div> 
48
      <div class="toc2"><a href="#QuickUpdate">Quick Update</a></div>
49
    <div class="toc1"><a href="#PreInstallation">Pre-Installation</a></div>
50
      <div class="toc2"><a href="#MinRequirements">Minimum Requirements</a></div> 
51
      <div class="toc2"><a href="#AdditionalRequiredSoftware">Additional Required Software</a></div>
52
    <div class="toc1"><a href="#AdditionalSoftwareSetup">Additional Software Setup</a></div>
53
      <div class="toc2"><a href="#AdditionalSoftwareJava">Java</a></div> 
54
      <div class="toc2"><a href="#AdditionalSoftwareOracle">Oracle</a></div>
55
      <div class="toc2"><a href="#AdditionalSoftwarePostgres">PostgreSQL</a></div>
56
      <div class="toc2"><a href="#AdditionalSoftwareAnt">Ant</a></div>
57
      <div class="toc2"><a href="#AdditionalSoftwareTomcat">Tomcat</a></div>
58
    <div class="toc1"><a href="#DownloadingMetacat">Download Metacat and Get War File</a></div>
59
      <div class="toc2"><a href="#DownloadMetacatBinary">Download Metacat Binary and Create War File</a></div>
60
      <div class="toc2"><a href="#DownloadMetacatSource">Download Metacat Source and Create War File</a></div>
61
    <div class="toc1"><a href="#InstallingMetacat">Installing Metacat</a></div>
62
      <div class="toc2"><a href="#CreateMetacatDirs">Create Metacat Directories</a></div>
63
      <div class="toc2"><a href="#InstallMetacatWar">Install Metacat War</a></div>
64
    <div class="toc1"><a href="#UpgradingMetacat">Upgrading Existing Metacat</a></div>
65
      <div class="toc2"><a href="#UpgradeStopMetacat">Stop the Running Metacat</a></div>
66
      <div class="toc2"><a href="#UpgradeDownloadMetacat">Download Latest Metacat Application</a></div>
67
      <div class="toc2"><a href="#UpgradeMetacatWar">Upgrade Metacat War</a></div>
68
   <div class="toc1"><a href="#RestartTomcat">Restart Tomcat</a></div>
69
      <div class="toc2"><a href="#UpgradeTroubleshooting">Troubleshooting</a></div>
70
      <div class="toc2"><a href="#UpgradeConfigureMetacat">Configure Metacat</a></div>       
71
    <div class="toc1"><a href="#Registry">Web Based Registry</a></div>
72
<!--
73
    <div class="toc1"><a href="#VersionNotes">Version Installation Notes</a></div>
74
      <div class="toc2"><a href="#1_9InstallNotes">1.9 Installation Notes</a></div> 
75
-->
76
  </div> 
77

  
78
<a name="QuickInstructions"></a><div class="header1">Quick Instructions</div>
79

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

  
107
  <div class=indent>
108
    <a name="InstallJava"></a><div class="header3">Install Java</div>
109
    <p>Install Java by typing:</p>
110
      <div class="code">sudo apt-get install sun-java5-jdk</div>
111
	<p>hit "ok" then "yes" for license agreement<p>
112
  </div>
113

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

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

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

  
248
<!--
249
<a name="SourceInstall"></a><div class="header1">Installing From Source Code</div>
250
<p>These documents are meant to outline the metacat installation process on specific platforms. They are 
251
<strong><em>not</em></strong> a substitute for the below instructions and only meant as a supplemental guideline. </p>  
252
  <a name="WindowsXP"></a><div class="header2">Windows XP</div> 
253
    <p> See the <a href="os_specific/install_metacat_windows.html">Windows XP installation instructions</a>.</p>
254
  <a name="Ubuntu8.04"></a><div class="header2">Ubuntu 8.04</div>
255
    <p> See the <a href="os_specific/install_metacat_ubuntu.html">Ubuntu 8.04 installation instructions</a>.</p>
256
  <a name="MacOSX"></a><div class="header2">Mac OS X</div>
257
    <p> See the <a href="os_specific/install_metacat_mac.html">Mac OS X installation instructions</a>.</p>
258
-->
259

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

  
291
<a name="AdditionalSoftwareSetup"></a><div class="header1">Additional Software Setup</div>
292
  <a name="AdditionalSoftwareJava"></a><div class="header2">Java</div>
293
  <p>You'll need a recent Java SDK; J2SE 1.4.2 or later is required.  The latest metacat release
294
  has been tested most extensively with <a href="http://java.sun.com/j2se/1.5.0/">J2SE 5.0</a>
295
  and this is the recommended version.
296
  Make sure that JAVA_HOME environment variable is properly set and that both
297
  java and javac are on your PATH. 
298
  </p>
299
  <a name="AdditionalSoftwareOracle"></a><div class="header2">Oracle 8i</div>
300
  <p>The Oracle RDBMS must be installed and running as a daemon on the system.
301
   In addition the JDBC listener must be enabled.  You can enable it by
302
   logging in as your Oracle user and typing the following:</p>
303
   
304
     <div class="code">lsnrctl start</div>
305
     
306
   <p>Your instance should have a table space of at least 5 MB (10 MB or higher 
307
   recommended).  You should also have a username specific to Metacat
308
   created and enabled.  This user must have most normal permissions 
309
   including CREATE SESSION, CREATE TABLE, CREATE INDEX, CREATE TRIGGER, 
310
   EXECUTE PROCEDURE, EXECUTE TYPE, etc.  If an action is unexplainably 
311
   rejected by Metacat it is probably because the user permissions are not
312
   correctly set.</p>
313
   
314
  <a name="AdditionalSoftwarePostgreSQL"></a><div class="header2">PostgreSQL</div>
315
  <p>PostgreSQL can be easily installed on most linux distributions and on
316
  Windows (using cygwin) and Mac OS X.  Using Fedora Core or RedHat Linux,
317
  you can install the rpms for postgres and then run </p>
318
  
319
    <div class="code">/etc/init.d/postgresql start</div> 
320
    
321
  <p>in order to start the database. 
322
  On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command
323
  to install postgres: 
324
    <div class="code">sudo apt-get install postgresql-8.0</div> and 
325
  then run 
326
    <div class="code">/etc/init.d/postgresql-8.0 start</div> to start.
327
  
328
  This initializes the data files.  You need to do a bit of configuration
329
  to create a database and set up a user account and allow internet access
330
  via jdbc.  See the postgres documentation for this, but here is a quick 
331
  start:
332
  <ul>
333
     <li>Switch to the "postgres" user account 
334
       <div class="code">sudo su - postgres</div></li>
335
     <li>Edit "data/pg_hba.conf", adding the following line to the file:<br>
336
       <div class="code">host   metacat  metacat      127.0.0.1         255.255.255.255   password</div>
337
     If your host uses IPv6 addresses, you may need this line instead:
338
       <div class="code">host   metacat  metacat      ::1               ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff password</div></li>
339
     <li>If you are using Postgresql pre-8.0, you must edit the "data/postgres.conf" file and uncomment and edit the line
340
     starting with "tcpip_socket" so that it reads 
341
       <div class="code">tcpip_socket = true</div></li>
342
     <li>Create metacat database by typing: 
343
       <div class="code">createdb metacat</div></li>
344
     <li>Log in using the postgres account and create a new "metacat" user account by typing:
345
       <div class="code">psql metacat</div> 
346
     <ul>
347
        <li>In postgres, run <div class="code">CREATE USER metacat WITH UNENCRYPTED PASSWORD 'apasswordyoulike';</div></li>
348
        <li>This creates a new account called metacat on the database named metacat</li>
349
        <li>Note: there are many ways to do this, so others such as using 
350
        ENCRYPTED passwords will work fine.</li>
351
     </ul>
352
     </li>
353
     <li>Exit the postgres account back to root and restart the postgres 
354
     database by typing:
355
       <div class="code">/etc/init.d/postgresql restart</div></li>
356
     <li>Test logging into the postgres db using the metacat account with 
357
     the following command: 
358
       <div class="code">psql -U metacat -W -h localhost metacat</div></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 &lt;tomcat_home&gt;.
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="DownloadingMetacat"></a><div class="header1">Download Metacat and Get War File</div>
384
 <p>There are several ways to wind up with a Metacat war file, which is needed for 
385
 installation.  These are: </p>
386
    <ul>
387
      <li>Download Metacat binary distribution - which will have a pre-built war file.</li>
388
      <li>Download Metacat source distribution - which will then need to be built in order to create a war file.</li>
389
      <li>Download Metacat source from SVN - which will then need to be built in order to create a war file.</li>
390
    </ul>
391
  <p>Since downloading the binary distribution is the easiest and most common install, it
392
  will be discussed here in detail.  Links to source download/build instructions are also
393
  included in case you would like to go that route.</p>
394
  <a name="DownloadMetacatBinary"></a><div class="header2">Download Metacat Binary and Create War File</div>
395

  
396
    <p>Browse to the 
397
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
398
      In the Metacat section, for Linux based systems, select the link that looks like:</p>
399
	  <div class="code">metacat-bin-X.X.X.tar.gz</div>
400
	  <p>for Windows systems, select the link that looks like:</p>
401
	  <div class="code">metacat-bin-X.X.X.zip</div>
402
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally.</p>
403
    <p>Extract the Metacat package files on Linux systems by typing:
404
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
405
    <p>or, on Windows, use your system unzip utility to extract the zip file.</p>
406
    <p>You should see a war file and several supporting files.  The location where these files
407
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
408
    of this documentation.
409
    
410
  <a name="DownloadMetacatSource"></a><div class="header2">Download Metacat Source and Create War File</div>
411

  
412
    <p>If you would like to download the Metacat source distribution or checkout the source
413
    code from SVN, go to the  
414
      <a href="./metacat-source-build.html">Download and Build Metacat From Source</a> page.
415

  
416
<a name="InstallingMetacat"></a><div class="header1">Installing Metacat</div>
417
  <p>This section is only for a new installation. If you are upgrading an existing Metacat, please skip
418
  this section and go to the next one - <a href="#UpgradingMetacat">Upgrading Existing Metacat</a></p>
419
  
420
  <p>Tomcat will look for it's application files (war files) in a configured directory.  
421
  This is typically the &lt;tomcat_home&gt;/webapps directory, but your instance of Tomcat may 
422
  be configured to look in a different directory.  We will refer to your Tomcat application directory 
423
  as &lt;tomcat_app_dir&gt;.</p>
424
     
425
  <a name="CreateMetacatDirs"></a><div class="header2">Create Metacat Directories</div>
426
    <p>Metacat uses a base directory to store such things as store data and metadata,
427
    temporary files and configuration backups.  This directory should be outside of the 
428
    Tomcat application directory since the application directory gets wiped out during an
429
    upgrade. Create the metacat utility base directory 
430
    by typing:</p>
431
      <div class="code">sudo mkdir <metacat_base_dir></div>
432
    <p>(Typically <metacat_base_dir> is '/var/metacat'.)  Remeber the directory you 
433
    choose, since you will be asked to configure Metacat to point to it after startup.</p>
434
    
435
    <p>Change the ownership of the directory by typing:</p>   
436
	  <div class="code">sudo chown -R &lt;tomcat_user&gt; /var/metacat</div>
437
    <p>where &lt;tomcat_user&gt; is the user that will start Tomcat.  If you are 
438
	starting Tomcat as the root user, you do not need to run the chown command.</p>
439
	
440
  <a name="InstallMetacatWar"></a><div class="header2">Install Metacat War</div> 
441
    <p>Copy the war file to Tomcat:</p>
442
	  <div class="code">sudo cp knb.war &lt;tomcat_app_dir&gt;</div>
443

  
444
<a name="UpgradingMetacat"></a><div class="header1">Upgrading Existing Metacat</div>
445
  <a name="protocol"></a>
446
  <p>The following instructions are for upgrading an existing Metacat.
447
  
448
  <a name="UpgradeStopMetacat"></a><div class="header2">Stop the Running Metacat</div>
449
   <p>To do this, login as the user that runs your tomcat server (often "tomcat"),
450
   go to &lt;tomcat_home&gt;/bin and type:</p>
451
   
452
   <div class="code">./shutdown.sh</div>  
453
  
454
  <a name="UpgradeDownloadMetacat"></a><div class="header2">Download Latest Metacat Application</div>
455
    <p>Browse to the 
456
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
457
      In the Metacat section, select the link that looks like:</p>
458
	  <div class="code">metacat-bin-X.X.X.tar.gz</div>
459
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally.</p>
460
    <p>Extract the Metacat package files by typing:</p>
461
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
462
    <p>You should see several files:</p>
463
    
464
    <ul>
465
    <li>knb.war - the Metacat application web archive file.</li>
466
    <li>knb - the web definition file used by Apache on ubuntu/debian Linux systems.</li>
467
    <li>jk.conf - the JkMount configuration file used by Apache on ubuntu/debian Linux systems.</li>
468
    <li>workers.properties - the workers definition file used by Apache on ubuntu/debian Linux systems.</li>
469
    <li>tomcat5.5 - the Tomcat startup script for Tomcat 5.5 installed with apt-get on ubuntu/debian Linux systems.</li>
470
    <li>authority - the optional LSID Server application web archive file.</li>
471
    </ul>
472
    
473
    <p>The location where these files
474
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
475
    of this documentation.</p>
476
 
477
   <a name="UpgradeMetacatWar"></a><div class="header2">Upgrade Metacat War</div> 
478
    <p>Tomcat will look for it's application files (war files) in a configured directory.  
479
    This is typically the &lt;tomcat_home&gt;/webapps directory, but your instance of Tomcat may 
480
    be configured to look in a different directory.  We will refer to your Tomcat application directory 
481
    as &lt;tomcat_app_dir&gt;.</p>
482
    
483
    <p>If desired, back up your existing war file with a date:</p>
484
      <div class="code">sudo mv &lt;tomcat_app_dir&gt;/knb.war &lt;tomcat_app_dir&gt;/knb.war.&lt;yyyymmdd&gt;</div>
485
    
486
    <p>Copy the war file to the Tomcat applications directory:</p>
487
	  <div class="code">sudo cp knb.war &lt;tomcat_app_dir&gt;</div>
488
	<p>Remove (or rename) the existing application directory:</p>
489
	  <div class="code">sudo rm -rf &lt;tomcat_home&gt;/webapps/knb</div>
490
	  <p> or </p>
491
	  <div class="code">sudo mv &lt;tomcat_home&gt;/webapps/knb &lt;tomcat_home&gt;/webapps/knb.&lt;yyyymmdd&gt;</div>
492
	<p>Restart Tomcat:</p>  
493
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
494
	<p>Tomcat will expand your war file into a new application directory at startup time.</p>
495
 
496
  <a name="RestartTomcat"></a><div class="header1">Restart Tomcat</div>
497
    <p>Once you have successfully installed Metacat, there is one more step.  Tomcat
498
    (and Apache if you have Tomcat integrated with it) must be restarted.  To do
499
    this, login as the user that runs your tomcat server (often "tomcat"),
500
    go to &lt;tomcat_home&gt;/bin and type: </p>
501
   
502
      <div class="code">./startup.sh</div>
503
   
504
    <p>In the Tomcat startup messages you should see something in the log file like:</p>
505
   
506
      <div class="code">Metacat: [WARN]: Metacat (1.8.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]</div>
507
     
508
    If you see that message Tomcat has successfully loaded the Metacat servlet.
509
    Next, try to run your new servlet.  Go to a web browser and type:</p>
510
   
511
      <div class="code">http://yourserver.yourdomain.com/yourcontext/</div>
512
     
513
    <p>You should substitute your context name for "yourcontext" in the url above.
514
    If everything is working correctly, you should see a query page followed
515
    by an empty result set.  Note that if you do not have Tomcat integrated with
516
    Apache you will probably have to type</p>
517
   
518
    <div class="code">http://yourserver.yourdomain.com:8080/yourcontext/</div>
519

  
520
  <a name="UpgradeTroubleshooting"></a><div class="header2">Troubleshooting</div>
521
  <p>If you see something like: 
522
  
523
    <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>
524
  
525
  <p>You should add this line: </p>
526
  
527
    <div class="code">JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</div> 
528
  <p>at the first line of the catalina.sh file in the tomcat bin directory. The reason is that 
529
  GeoServer uses X11 windows to draw graphics.</p>
530
  
531
  <a name="UpgradeConfigureMetacat"></a><div class="header2">Configure Metacat</div>
532
  <p>Once you see the Metacat configuration screen, you can follow the instructions in the 
533
  <a href="./metacatconfigure.html"> Configuring Metacat Section</a> 
534
  to complete the internal configuration of Metacat.</p>
535

  
536
<a name="Registry"></a><div class="header1">Web Based Registry</div>
537
  <p>The registry allows users to upload simple metadata documents directly from the web.  See the separate 
538
  <a href="registry_installation.html">Registry Installation Guide</a>.</p><br/><br/>
539
</body>
540
</html>
0 541

  
docs/user/os_specific/install_metacat_mac.html
37 37
</p>
38 38

  
39 39
  <p class="emphasis">
40
	This is a terse cheatsheet for installing metacat with postgres on os X. Please see the <a href="../metacatinstall.html">general instructions</a> for the full details.
40
	This is a terse cheatsheet for installing metacat with postgres on os X. Please see the <a href="../metacat-install.html">general instructions</a> for the full details.
41 41
  </p>
42 42
</td>
43 43
</tr>
docs/user/index.html
34 34
<tr>
35 35
  <td>
36 36
  <p><a href="/software/download.html">Download Metacat</a></p>
37
  <p><a href="./metacatinstall.html">Metacat Installation Instructions</a></p>
37
  <p><a href="./metacat-install.html">Metacat Installation Instructions</a></p>
38 38
  <p>Metacat is a flexible metadata database. It utilizes 
39 39
     <a href="http://www.w3.org/TR/REC-xml" target="offline">XML</a> as a 
40 40
     common syntax for representing the large number of metadata content
docs/user/replication.html
313 313

  
314 314
<a name="ControlPanel"></a><div class="header1">The Replication Control Panel:</div>      
315 315
  There is an html control panel for controling replication.  After
316
  <a href="./Metacatinstall.html">installing</a> Metacat, you can access
316
  <a href="./Metacat-install.html">installing</a> Metacat, you can access
317 317
  it by going through the Metacat servlet context you have setup and calling up
318 318
  replControl.html.  For instance, if you setup a Metacat servlet instance 
319 319
  called 'knb' you would probably type 
docs/user/metacat-source-build.html
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-24 11:57:40 -0800 (Mon, 24 Nov 2008) $'
10
  *    '$Revision: 4621 $'
11
  *
12
  *
13
  -->
14
  
15
<!DOCTYPE html PUBLIC "-//W3C//DTD html 4.0//EN">
16
<html>
17

  
18
<head>
19
  <title>Metacat Source Download and Build 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 Source Download and Build 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">Table of Contents</div>
45
  <div class="toc">
46
    <div class="toc1"><a href="#Intro">Introduction</a></div>
47
    <div class="toc1"><a href="#GetSource">Get Metacat Source</a></div>
48
      <div class="toc2"><a href="#SourceDistribution">Source Distribution</a></div> 
49
      <div class="toc2"><a href="#SVN">SVN Checkout</a></div>
50
    <div class="toc1"><a href="#BuildFromSource">Build From Source</a></div>
51
      <div class="toc2"><a href="#PrepareBuild">Prepare Build</a></div>
52
      <div class="toc2"><a href="#DoAntBuild">Do Ant Build</a></div>
53
  </div> 
54

  
55
<a name="Intro"></a><div class="header1">Introduction</div>
56
  <p>Metacat source can be downloaded either by getting and extracting the 
57
  source distribution, or by checking out the code from the repository.</p>
58
  
59
  <p>Reasons for choosing one versus the other might be:</p>
60
  <ul>
61
  <li>Source Distribution - this is a faster download since the code is compressed.  You
62
  might choose this if you want a stable versioned release, but you prefer to have
63
  all of your applications built on the server where it will run.  (Although it shouldn't
64
  matter where a java application is built.)</li>
65
  <li>SVN Checkout - there are several reasons for choosing a checked out version of 
66
  the code.  One is that you may want to build from the head of the code to pick up
67
  new changes that are not yet in a versioned build.  Conversely, you may want to build
68
  off of an older tag, to avoid an issue that was introduced in a build.  Lastly, you 
69
  may want to develop and submit code to the Metacat repository</li>
70
  </ul>
71
  
72
  <p>In order to check out Metacat, you will need both Subversion (SVN) and CVS clients
73
  installed and configured on your system.  This is because, while Metacat has been 
74
  migrated to SVN, some of its supporting libraries (eml, utlities and seek) have not 
75
  yet been migrated.  Eventually, SVN will be the only versioning client you will need.  
76
  You will need to make sure you have the appropriate permissions on these systems</p>
77
  
78
  <p>For more information on installing SVN and CVS, please visit the following sites:
79
  
80
  <ul>
81
  <li><a href="http://subversion.tigris.org">The Subversion homepage</a></li>
82
  <li><a href="http://ximbiot.com/cvs/wiki/">The Ximbiot CVS homepage</a></li>
83
  </ul>
84
  
85
  </p>You will also need Apache Ant to do the build.  If you have not already 
86
  installed Ant, you can get it at:
87
  
88
  <ul>
89
  <li><a href="http://ant.apache.org/">The Apache Ant homepage</a></li>
90
  </ul>
91

  
92
<a name="GetSource"></a><div class="header1">Get Metacat Source</div>
93

  
94
  <a name="SourceDistribution"></a><div class="header2">Source Distribution</div>  
95
    <p>To get the Metacat source distribution, browse to the 
96
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
97
      In the Metacat section, for Linux based systems, select the link that looks like:</p>
98
	  <div class="code">metacat-src-X.X.X.tar.gz</div>
99
	  <p>for Windows systems, select the link that looks like:</p>
100
	  <div class="code">metacat-src-X.X.X.zip</div>
101
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally in the directory 
102
    where your source should live.</p>
103
    <p>Extract the Metacat package files on Linux systems by typing:
104
      <div class="code">tar -xvzf metacat-src-X.X.X.tar.gz</div>
105
    <p>or, on Windows, use your system unzip utility to extract the zip file.</p>
106
    <p>You should see the full Metacat source tree.</p>
107
 
108
  <a name="SVN"></a><div class="header2">SVN Checkout</div> 
109
    <p>To check out the code from SVN, go to the directory where you would like the code 
110
    to live and type:</p>
111
      <div class="code">svn co https://code.ecoinformatics.org/code/metacat/tags/METACAT_&lt;rev&gt; metacat</div>
112
    Where &lt;rev&gt; is the version of the code you want to check out (like 1_9). </p>
113
    
114
    <p>If you are trying to check out the head, type:</p>
115
      <div class="code">svn co https://code.ecoinformatics.org/code/metacat/trunk metacat</div>
116
      
117
    <p>You should see a list of files as they check out.</p>
118
    
119
  <a name="BuildFromSource"></a><div class="header1">Build From Source</div>
120
     <p>You should now have the Metacat source in a directory named "metacat" in your
121
     code directory (We will refer to the metacat source directory as &lt;metacat_src_dir&gt;.
122
     
123
  <a name="PrepareBuild"></a><div class="header2">Prepare Build</div>   
124
    <p>Edit the file at:</p>
125
      <div class="code">&lt;metacat_src_dir&gt;/build.properties</div> 
126
    <p>Make sure that the "build.tomcat.dir" property is set to your tomcat installation
127
    directory.  For instance:</p>
128
      <div class="code">build.tomcat.dir=/usr/local/tomcat</div>
129
    <p>Metacat will use some of the native Tomcat libraries during the build.</p>
130
    
131
    <p>If your cvs user is something other than the user your are logged in as, you
132
    will need to change the ${env.USER} part of the cvsroot property to be your cvs 
133
    user.  For instance:</p>
134
      <div class="code">cvsroot=:ext:cvs-user@cvs.ecoinformatics.org:/cvs</div>
135
    <p> where your cvs user name is "cvs-user"</p> 
136
    
137
  <a name="DoAntBuild"></a><div class="header2">Do Ant Build</div>   
138
    <p>In the &lt;metacat_src_dir&gt;, run: </p>
139
      <div class="code">ant fullclean build-metacat</div>
140
      
141
    <p>You will see the individual modules get built.  You will be prompted
142
    for your cvs password several times.  You should see a "BUILD SUCCESSFUL"
143
    message at the end.</p>
144
    
145
    <p>You should see a new file named:</p>
146
      <div class="code">&lt;metacat_src_dir&gt;/dist/knb.war</div>
147
    <p>This file will be used during the
148
      <a href="./metacat-install.html#InstallingMetacat">Metacat Installation</a>.</p>
149
      
150
  <br>
151
    
152
</body>
153
</html>
0 154

  

Also available in: Unified diff