Project

General

Profile

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: 2009-02-27 10:39:17 -0800 (Fri, 27 Feb 2009) $'
10
  *    '$Revision: 4817 $'
11
  *
12
  *
13
  -->
14
  
15
<!DOCTYPE html PUBLIC "-//W3C//DTD html 4.0//EN">
16
<html>
17

    
18
<head>
19
  <title>Metacat Linux 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 Linux 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="#Intro">Introduction</a></div> 
47
      <div class="toc2"><a href="#DifferentOptions">Different Installation Options</a></div> 
48
      <div class="toc2"><a href="#ThisDoc">Organization Of This Page</a></div>
49
    <div class="toc1"><a href="#QuickInstallation">Quick Installation</a></div> 
50
      <div class="toc2"><a href="#DownloadMetacatInstall">Download Metacat Package</a></div> 
51
      <div class="toc2"><a href="#CreateDirs">Create Metacat Directories</a></div> 
52
      <div class="toc2"><a href="#InstallJava">Install Java</a></div> 
53
      <div class="toc2"><a href="#InstallApache">Install Apache</a></div> 
54
      <div class="toc2"><a href="#InstallTomcat">Install Tomcat</a></div> 
55
      <div class="toc2"><a href="#InstallPostgres">Install PostgreSQL Database</a></div> 
56
      <div class="toc2"><a href="#QuickInstallMetacatWar">Install Metacat War</a></div> 
57
      <div class="toc2"><a href="#QuickInstallLsidWar">Install LSID War</a></div> 
58
      <div class="toc2"><a href="#ConfigureMetacatInstall">Configure Metacat</a></div> 
59
    <div class="toc1"><a href="#QuickUpdate">Quick Update</a></div>
60
      <div class="toc2"><a href="#DownloadMetacatUpdate">Download Metacat Package</a></div> 
61
      <div class="toc2"><a href="#BackupApplication">Backup Existing Metacat Installation</a></div> 
62
      <div class="toc2"><a href="#QuickUpdateMetacatWar">Update Metacat War</a></div> 
63
      <div class="toc2"><a href="#QuickUpdateLsidWar">Update LSID War</a></div> 
64
      <div class="toc2"><a href="#ConfigureMetacatUpdate">Configure Metacat</a></div> 
65
    <div class="toc1"><a href="#PreInstallation">Pre-Installation</a></div>
66
      <div class="toc2"><a href="#MinRequirements">Minimum Requirements</a></div> 
67
      <div class="toc2"><a href="#AdditionalRequiredSoftware">Additional Required Software</a></div>
68
    <div class="toc1"><a href="#AdditionalSoftwareSetup">Additional Software Setup</a></div>
69
      <div class="toc2"><a href="#AdditionalSoftwareJava">Java</a></div> 
70
      <div class="toc2"><a href="#AdditionalSoftwareOracle">Oracle</a></div>
71
      <div class="toc2"><a href="#AdditionalSoftwarePostgreSQL">PostgreSQL</a></div>
72
      <div class="toc2"><a href="#AdditionalSoftwareAnt">Ant</a></div>
73
      <div class="toc2"><a href="#AdditionalSoftwareApache">Apache</a></div>
74
      <div class="toc2"><a href="#AdditionalSoftwareTomcat">Tomcat</a></div>
75
    <div class="toc1"><a href="#DownloadingMetacat">Download Metacat and Get War File</a></div>
76
      <div class="toc2"><a href="#DownloadMetacatBinary">Download Metacat Binary and Get War File</a></div>
77
      <div class="toc2"><a href="#DownloadMetacatSourceDist">Download Metacat Source Distribution</a></div>
78
      <div class="toc2"><a href="#DownloadMetacatSourceSVN">Download Metacat Source From SVN</a></div>
79
      <div class="toc2"><a href="#CreateSourceWar">Create War From Source</a></div>
80
    <div class="toc1"><a href="#InstallingMetacat">Installing Metacat</a></div>
81
      <div class="toc2"><a href="#CreateMetacatDirs">Create Metacat Directories</a></div>
82
      <div class="toc2"><a href="#InstallMetacatWar">Install Metacat Binary (War)</a></div>
83
      <div class="toc2"><a href="#InstallMetacatSource">Install Metacat From Source</a></div>
84
    <div class="toc1"><a href="#UpgradingMetacat">Upgrading Existing Metacat</a></div>
85
      <div class="toc2"><a href="#UpgradeStopMetacat">Stop the Running Metacat</a></div>
86
      <div class="toc2"><a href="#UpgradeDownloadMetacat">Download Latest Metacat Application</a></div>
87
      <div class="toc2"><a href="#UpgradeMetacatWar">Upgrade Metacat Binary (War)</a></div>
88
      <div class="toc2"><a href="#UpgradeMetacatSource">Upgrade Metacat From Source</a></div>
89
   <div class="toc1"><a href="#RestartTomcat">Restart Tomcat</a></div>
90
      <div class="toc2"><a href="#UpgradeTroubleshooting">Troubleshooting</a></div>
91
      <div class="toc2"><a href="#UpgradeConfigureMetacat">Configure Metacat</a></div>       
92
    <div class="toc1"><a href="#Registry">Web Based Registry</a></div>
93
  </div> 
94

    
95
<a name="Intro"></a><div class="header1">Introduction</div>
96
  <a name="DifferentOptions"></a><div class="header2">Different Installation Options</div>
97
  <p>There are many different options to consider when installing Metacat.  Some of these
98
  are: </p>
99
  <ul>
100
  <li>Operating System - Metacat is a Java servlet application.  As such, you can run
101
  it on many different operating system.  It has been tested against Linux, MacOS and 
102
  MicroSoft Windows.  The optimal installation is on Ubuntu Linux.</li>
103
  <li>Tomcat standalone or in conjunction with Apache web server - The Tomcat server 
104
  can be run alone as a web server.  However, it is not as robust a server,
105
  and does't allow for the same level of customization as Apache.  The recommended 
106
  configuration is Tomcat running in conjunction with Apache</li>
107
  <li>Binary versus source installation - There are three ways to get and install 
108
  the Metacat installation.
109
    <ul>
110
  	<li>Binary Distribution Installation - download the Metacat war distribution and install it 
111
  	into the web applications directory</li>
112
  	<li>Source Distribution Installation - download the source code distribution, build it and 
113
  	install the resultant war file into the web application directory.</li>
114
  	<li>Source Checkout Installation - check the source code out from the Subversion 
115
  	repository, build it and install the resultant war file into the web application directory.</li>
116
  	</ul>
117
  The recommended installation procedure is binary distribution installation.</li>
118
  </ul>
119
  
120
  <p>The administrator will need to decide which combinations of these option are best
121
  suited to their system</p>
122
  
123
  <a name="ThisDoc"></a><div class="header2">Organization Of This Page</div>
124
  <p> The first couple of sections on this page deal with quick command line 
125
  instructions for installing and upgrading Metacat in the optimal environment, which
126
  is a binary distribution installation with Apache on Ubuntu Linux.</p>
127
  
128
  <p>The remainder of the page deals with more detailed instructions including other 
129
  installation options.</p>
130

    
131
<a name="QuickInstallation"></a><div class="header1">Quick Installation</div>
132
  <p>These are the installation instructions for a system that has Ubuntu 8.04 installed
133
  and has never had Metacat installed on it:</p>
134
 
135
  <a name="DownloadMetacatInstall"></a><div class="header2">Download Metacat Package</div>
136
    <ul>
137
    <li>Browse to the 
138
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
139
      In the Metacat section, select the link that looks like:
140
	  <div class="code">metacat-bin-X.X.X.tar.gz</div>
141
    where X.X.X is the latest version of Metacat.  Choose to save the file locally.</li>
142
    <li>Extract the Metacat package files by typing:
143
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div></li>
144
    <li>You should see a war file and several supporting files.  The location where these files
145
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
146
    of this documentation.</li>
147
    </ul>
148
  
149
  <a name="CreateDirs"></a><div class="header2">Create Metacat Directories</div>
150
    <ul>
151
    <li>Create the metacat utility base directory by typing:
152
      <div class="code">sudo mkdir /var/metacat</div>
153
	  <div class="code">sudo chown -R &lt;tomcat_user&gt; /var/metacat</div>
154
    where &lt;tomcat_user&gt; is the user that will start Tomcat.  If you are 
155
	starting Tomcat as the root user, you do not need to run the chown command.</li>
156
    </ul>
157

    
158
  <a name="InstallJava"></a><div class="header2">Install Java</div>
159
    <ul>
160
    <li>Install Java by typing:
161
      <div class="code">sudo apt-get install sun-java5-jdk</div></li>
162
	<li>hit "ok" then "yes" for license agreement</li>
163
	</ul>
164

    
165
  <a name="InstallApache"></a><div class="header2">Install Apache</div>
166
    <ul>
167
    <li>Install Apache and and Mod JK packages by typing:	
168
      <div class="code">sudo apt-get install apache2 libapache2-mod-jk</div></li>
169
    <li>Set up Mod JK apache configuration by typing:
170
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/jk.conf /etc/apache2/mods-available</div>
171
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/workers.properties /etc/apache2</div></li>
172
    <li>Enable Apache Mod JK by typing:
173
      <div class="code">sudo a2dismod jk</div>
174
      <div class="code">sudo a2enmod jk</div></li>
175
    <li>Set up and enable knb (Metacat) site configurations by typing:
176
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/knb /etc/apache2/sites-available</div>
177
      <div class="code">sudo a2ensite knb</div></li>
178
    <li>If you want to run an LSID server along with the Metacat server, set up and enable the authority service site 
179
      configurations by typing:
180
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/authority /etc/apache2/sites-available</div>
181
      <div class="code">sudo a2ensite authority</div></li>
182
    <li>Restart apache to bring in changes by typing:
183
      <div class="code">sudo /etc/init.d/apache2 force-reload</div></li>
184
    </ul>
185
     
186
  <a name="InstallTomcat"></a><div class="header2">Install Tomcat</div>
187
    <ul>
188
    <li>Install Tomcat 5.5 by typing:
189
      <div class="code">sudo sudo apt-get install tomcat5.5</div> </li>
190
    <li>Install Metacat friendly Tomcat startup script by typing:    
191
      <div class="code">sudo /etc/init.d/tomcat5.5 stop</div>    
192
      <div class="code">sudo mv /etc/init.d/tomcat5.5 /etc/init.d/tomcat5.5.bak</div>
193
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/tomcat5.5 /etc/init.d/tomcat5.5</div>
194
      <div class="code">sudo chmod +x /etc/init.d/tomcat5.5</div></li>
195
    </ul>
196
    
197
  <a name="InstallPostgres"></a><div class="header2">Install PostgreSQL Database</div> 
198
    <ul>
199
    <li>Install PostgreSQL by typing:</p>
200
      <div class="code">sudo apt-get install postgresql</div></li>
201
    <li>Change to postgres user:
202
      <div class="code">sudo su - postgres</div></li>
203
    <li>Setup empty Metacat database instance editing the postgreSQL configuration file:  
204
      <div class="code">gedit /etc/postgresql/8.3/main/pg_hba.conf</div></li>
205
    and adding the following line:
206
      <div class="code">host metacat metacat 127.0.0.1 255.255.255.255 password</div></li>
207
    <li>Save the file, then create the metacat instance:
208
      <div class="code">createdb metacat</div></li>
209
    <li>Log into postgreSQL by typing:
210
	  <div class="code">psql metacat</div>
211
	and create the metacat user by typing at the psql prompt:
212
	  <div class="code">CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password';</div>
213
	where your_password is whatever password you would like for the metacat user.</li>
214
	<li>Exit PostgreSQL by typing
215
	  <div class="code">\q</div></li>
216
	<li>Restart the PostgreSQL database to bring in changes:
217
	  <div class="code">/etc/init.d/postgresql-8.3 restart</div></li>
218
	<li>Log out of the postgres user account by typing:
219
	  <div class="code">logout</div></li>
220
	<li>Test the installation and metacat account by typing:
221
	  <div class="code">psql -U metacat -W -h localhost metacat</div></li>
222
	<li>Log back out of postgreSQL:
223
	  <div class="code">\q</div></li>
224
	</ul>
225
	
226
  <a name="QuickInstallMetacatWar"></a><div class="header2">Install Metacat War</div> 
227
    <ul>
228
    <li>Copy the war file to Tomcat:
229
	  <div class="code">sudo cp &lt;metacat_package_dir&gt;/knb.war /usr/share/tomcat5.5/webapps</div></li>
230
	<li>Restart Tomcat:
231
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div></li>
232
  	</ul>
233
  	
234
  <a name="QuickInstallLsidWar"></a><div class="header2">Install LSID War</div> 
235
    <ul>
236
    <li>If you want to run an LSID server along with the Metacat server, copy the 
237
    authority.war file to Tomcat:
238
	  <div class="code">sudo cp &lt;metacat_package_dir&gt;/authority.war /usr/share/tomcat5.5/webapps</div></li>
239
	<li>Restart Tomcat:  
240
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div></li>
241
	</ul>
242
		
243
  <a name="ConfigureMetacatInstall"></a><div class="header2">Configure Metacat</div> 
244
    <p>Refer to the documentation on <a href="./metacat-configure.html">Metacat Confguration</a>
245
    to complete your installation of Metacat.</p>
246
    
247
  <a name="QuickUpdate"></a><div class="header1">Quick Update</div>
248
  <p>These are the instructions for a system that already has Metacat installed on it, 
249
  but needs a Metacat upgrade:</p>
250
  
251
  <a name="DownloadMetacatUpdate"></a><div class="header2">Download Metacat Package</div>
252
    <ul>
253
    <li>Browse to the 
254
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
255
      In the Metacat section, select the link that looks like:
256
	  <div class="code">metacat-bin-X.X.X.tar.gz</div>
257
    where X.X.X is the latest version of Metacat.  Choose to save the file locally.</li>
258
    <li>Extract the Metacat package files by typing:
259
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
260
    You should see a war file and several supporting files.  The location where these files
261
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
262
    of this documentation.</li>
263
    </ul>
264
    
265
  <a name="BackupApplication"></a><div class="header2">Backup Existing Metacat Installation</div>
266
    <ul>
267
    <li>To be safe, it is best to backup the existing Metacat installation.  Do so by typing: </p>
268
	  <div class="code">cp &lt;web_app_dir&gt;/knb &lt;web_app_dir&gt;/knb.&lt;yyyymmdd&gt;</div>
269
	  <div class="code">cp &lt;web_app_dir&gt;/knb.war &lt;web_app_dir&gt;/knb.war.&lt;yyyymmdd&gt;</div>
270
	Of course, you can use any backup strategy you like (or none at all).</p>
271
	</ul>
272
  
273
  <a name="QuickUpdateMetacatWar"></a><div class="header2">Update Metacat War</div> 
274
    <ul>
275
    <li>Copy the war file to Tomcat:
276
	  <div class="code">sudo cp knb.war /usr/share/tomcat5.5/webapps</div></li>
277
	<li>Restart Tomcat:  
278
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div></li>
279
	</ul>
280
  	
281
  <a name="QuickUpdateLsidWar"></a><div class="header2">Update LSID War</div> 
282
    <ul>
283
    <li>If you want to run an LSID server along with the Metacat server, copy the 
284
    authority.war file to Tomcat:
285
	  <div class="code">sudo cp &lt;metacat_package_dir&gt;/authority.war /usr/share/tomcat5.5/webapps</div></li>
286
	<li>Restart Tomcat:  
287
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div></li>
288
	</ul>
289
		
290
  <a name="ConfigureMetacatUpdate"></a><div class="header2">Configure Metacat</div> 
291
    <p>Refer to the documentation on <a href="./metacat-configure.html">Metacat Confguration</a>
292
    to complete your installation of Metacat.</p>
293

    
294
<a name="PreInstallation"></a><div class="header1">Pre-Installation</div>
295
  <a name="MinRequirements"></a><div class="header2">Minimum Requirements</div> 
296
  <p>
297
   Installing Metacat requires a server running an SQL92 compliant database
298
   (Oracle 8i or Postgresql recommended) with at least 128MB RAM, and a Pentium III class
299
   processor or higher.  The amount of disk space required depends on the
300
   size of your RDBMS tablespace (which should be at least 10 MB, 
301
   however Metacat itself requires only about 1 MB of free space after 
302
   installation).  These instructions assume a Linux environment but may
303
   work on other UNIX type environments, however this has not been tested.
304
  </p>
305
  
306
  <a name="AdditionalRequiredSoftware"></a><div class="header2">Additional Required Software</div>
307
  <p>
308
   The server on which you wish to install Metacat must have the following
309
   software installed and running correctly before attempting to install
310
   Metacat.
311
   <ul>
312
     <li><a href="http://www.oracle.com">Oracle 8i</a> (or another SQL92
313
         compliant RDBMS like Postgres)</li>
314
     <li><a href="http://jakarta.apache.org/ant/index.html">Apache Jakarta-Ant</a>
315
     </li>
316
     <li><a href="http://jakarta.apache.org/tomcat/index.html">Apache Jakarta-Tomcat</a>
317
       <p class="emphasis">Note: For a more robust web serving environment, 
318
       Apache web server should
319
       be installed along with Tomcat and the two should be integrated
320
       as described on the Apache web site.</p>
321
     </li>
322
   </ul>
323
  </p>
324

    
325
<a name="AdditionalSoftwareSetup"></a><div class="header1">Additional Software Setup</div>
326
  <a name="AdditionalSoftwareJava"></a><div class="header2">Java</div>
327
  <p>You'll need a recent Java SDK; J2SE 1.4.2 or later is required.  The latest metacat release
328
  has been tested most extensively with <a href="http://java.sun.com/j2se/1.5.0/">J2SE 5.0</a>
329
  and this is the recommended version.
330
  Make sure that JAVA_HOME environment variable is properly set and that both
331
  java and javac are on your PATH. 
332
  </p>
333
  <a name="AdditionalSoftwareOracle"></a><div class="header2">Oracle 8i</div>
334
  <p>The Oracle RDBMS must be installed and running as a daemon on the system.
335
   In addition the JDBC listener must be enabled.  You can enable it by
336
   logging in as your Oracle user and typing the following:</p>
337
   
338
     <div class="code">lsnrctl start</div>
339
     
340
   <p>Your instance should have a table space of at least 5 MB (10 MB or higher 
341
   recommended).  You should also have a username specific to Metacat
342
   created and enabled.  This user must have most normal permissions 
343
   including CREATE SESSION, CREATE TABLE, CREATE INDEX, CREATE TRIGGER, 
344
   EXECUTE PROCEDURE, EXECUTE TYPE, etc.  If an action is unexplainably 
345
   rejected by Metacat it is probably because the user permissions are not
346
   correctly set.</p>
347
   
348
  <a name="AdditionalSoftwarePostgreSQL"></a><div class="header2">PostgreSQL</div>
349
  <p>PostgreSQL can be easily installed on most linux distributions and on
350
  Windows (using cygwin) and Mac OS X.  Using Fedora Core or RedHat Linux,
351
  you can install the rpms for postgres and then run </p>
352
  
353
    <div class="code">/etc/init.d/postgresql start</div> 
354
    
355
  <p>in order to start the database. 
356
  On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command
357
  to install postgres: 
358
    <div class="code">sudo apt-get install postgresql-8.0</div> and 
359
  then run 
360
    <div class="code">/etc/init.d/postgresql-8.0 start</div> to start.
361
  
362
  This initializes the data files.  You need to do a bit of configuration
363
  to create a database and set up a user account and allow internet access
364
  via jdbc.  See the postgres documentation for this, but here is a quick 
365
  start:
366
  <ul>
367
     <li>Switch to the "postgres" user account 
368
       <div class="code">sudo su - postgres</div></li>
369
     <li>Edit "data/pg_hba.conf", adding the following line to the file:<br>
370
       <div class="code">host   metacat  metacat      127.0.0.1         255.255.255.255   password</div>
371
     If your host uses IPv6 addresses, you may need this line instead:
372
       <div class="code">host   metacat  metacat      ::1               ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff password</div></li>
373
     <li>If you are using Postgresql pre-8.0, you must edit the "data/postgres.conf" file and uncomment and edit the line
374
     starting with "tcpip_socket" so that it reads 
375
       <div class="code">tcpip_socket = true</div></li>
376
     <li>Create metacat database by typing: 
377
       <div class="code">createdb metacat</div></li>
378
     <li>Log in using the postgres account and create a new "metacat" user account by typing:
379
       <div class="code">psql metacat</div> 
380
     <ul>
381
        <li>In postgres, run <div class="code">CREATE USER metacat WITH UNENCRYPTED PASSWORD 'apasswordyoulike';</div></li>
382
        <li>This creates a new account called metacat on the database named metacat</li>
383
        <li>Note: there are many ways to do this, so others such as using 
384
        ENCRYPTED passwords will work fine.</li>
385
     </ul>
386
     </li>
387
     <li>Exit the postgres account back to root and restart the postgres 
388
     database by typing:
389
       <div class="code">/etc/init.d/postgresql restart</div></li>
390
     <li>Test logging into the postgres db using the metacat account with 
391
     the following command: 
392
       <div class="code">psql -U metacat -W -h localhost metacat</div></li>
393
  </ul>
394
  </p>
395
  
396
  <a name="AdditionalSoftwareAnt"></a><div class="header2">Ant</div>
397
  <p>
398
   Ant is a Java based build application similar to Make on UNIX systems.  
399
   It takes in installation parameters from a file in the root installation
400
   directory named "build.xml".  The Metacat CVS module contains a default
401
   build.xml file that may require some modification upon installation.  Ant
402
   should be installed on the system and the "ant" executable shell script 
403
   should be available in the users path. The latest metacat release was tested with 
404
   Ant 1.6.5. <!-- We note that the current build is 
405
   not working with Ant 1.6.x, so you'll need to use an earler version.  We have 
406
   successfully used Ant 1.5.1, 1.5.2, and some earlier versions. -->
407
  </p>
408
  
409
  <a name="AdditionalSoftwareApache"></a><div class="header2">Apache</div>
410
  <p>
411
    If you are running Ubuntu/Debian, you can install the Apache web server by typing:</p>
412
      <div class="code">sudo apt-get install apache2</div>
413
    Otherwise, you can get Apache from <a href="http://httpd.apache.org/download.cgi">the Apache Tomcat page</a>.
414
  </p>
415
  
416
  <a name="AdditionalSoftwareTomcat"></a><div class="header2">Tomcat</div>
417
  <p>
418
    Install Tomcat into the directory of your choice. The directory in which 
419
    you install Tomcat itself will be referred to as the &lt;tomcat_home&gt;.
420
    We recommend that you install Tomcat version 5.5.  If you are running 
421
    Ubuntu/Debian, you can get Tomcat by typing:</p>
422
      <div class="code">sudo apt-get install tomcat5.5</div>
423
    Otherwise, you can get Tomcat from <a href=" http://jakarta.apache.org/tomcat/index.html">the Apache Tomcat page</a>.
424
  </p>
425

    
426
<a name="DownloadingMetacat"></a><div class="header1">Download Metacat and Get War File</div>
427
 <p>There are several ways to wind up with a Metacat war file, which is needed for 
428
 installation.  These are: </p>
429
    <ul>
430
      <li>Download Metacat binary distribution - which will have a pre-built war file.</li>
431
      <li>Download Metacat source distribution - which will then need to be built in order to create a war file.</li>
432
      <li>Download Metacat source from SVN - which will then need to be built in order to create a war file.</li>
433
    </ul>
434
  <p>Since downloading the binary distribution is the easiest and most common install, it
435
  will be discussed here in detail.  Links to source download/build instructions are also
436
  included in case you would like to go that route.</p>
437

    
438
<a name="DownloadMetacatBinary"></a><div class="header2">Download Metacat Binary and Get War File</div>
439
    <p>Browse to the 
440
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
441
      In the Metacat section, for Linux based systems, select the link that looks like:</p>
442
	  <div class="code">metacat-bin-X.X.X.tar.gz</div>
443
	  <p>for Windows systems, select the link that looks like:</p>
444
	  <div class="code">metacat-bin-X.X.X.zip</div>
445
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally.</p>
446
    <p>Extract the Metacat package files on Linux systems by typing:
447
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
448
    <p>or, on Windows, use your system unzip utility to extract the zip file.</p>
449
    <p>You should see a war file and several supporting files.  The location where these files
450
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
451
    of this documentation.
452
    
453
<a name="DownloadMetacatSourceDist"></a><div class="header2">Download Metacat Source Distribution</div>	
454
  <p>To get the Metacat source distribution, browse to the 
455
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
456
      In the Metacat section, for Linux based systems, select the link that looks like:</p>
457
	  <div class="code">metacat-src-X.X.X.tar.gz</div>
458
	  <p>for Windows systems, select the link that looks like:</p>
459
	  <div class="code">metacat-src-X.X.X.zip</div>
460
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally in the directory 
461
    where your source should live.</p>
462
    <p>Extract the Metacat package files on Linux systems by typing:
463
      <div class="code">tar -xvzf metacat-src-X.X.X.tar.gz</div>
464
    <p>or, on Windows, use your system unzip utility to extract the zip file.</p>
465
    <p>Rename the metacat-X.X.X directory to metacat.</p>
466
    <p>Note that you do not need to create the war file directly with a source installation
467
    since the Ant build file has an "install" target that will build and deploy the war
468
    for you.  See the <a href="#InstallingMetacat">Installing Metacat</a> for instructions.</p>
469

    
470
<a name="DownloadMetacatSourceSVN"></a><div class="header2">Download Metacat Source From SVN</div>
471
  <p>If you are checking out Metacat code from the SVN repository, you will need both 
472
  Subversion (SVN) and CVS clients installed and configured on your system.  Both are needed
473
  because, while Metacat has been migrated to SVN, some of its supporting libraries (eml, 
474
  utilities and seek) have not yet been migrated.  Eventually, SVN will be the only versioning 
475
  client you will need.  You will need to make sure you have the appropriate accounts on these 
476
  systems.  You won't have to worry about SVN or CVS if you are installing from a Metacat
477
  source distribution.  These have all the required dependencies built in.</p>
478
  
479
  <p>If you have not already installed Subversion and you are running Ubuntu/Debian, you can 
480
  get it by typing:</p>
481
    <div class="code">sudo apt-get install subversion</div>
482
    
483
  <p>Otherwise, you can get if from <a href="http://subversion.tigris.org">The Subversion homepage</a></p>
484
  
485
  <p>If you have not already installed CVS and you are running Ubuntu/Debian, you can 
486
  get it by typing:</p>
487
    <div class="code">sudo apt-get install cvs</div>
488
    
489
  <p>Otherwise, you can get it from <a href="http://ximbiot.com/cvs/wiki/">The Ximbiot CVS homepage</a></p>
490
  
491
  <p>To check out the code from SVN, go to the directory where you would like the code 
492
    to live and type:</p>
493
      <div class="code">svn co https://code.ecoinformatics.org/code/metacat/tags/METACAT_&lt;rev&gt; metacat</div>
494
    <p>Where &lt;rev&gt; is the version of the code you want to check out (like 1_9). </p>
495
    
496
    <p>If you are trying to check out the head, type:</p>
497
      <div class="code">svn co https://code.ecoinformatics.org/code/metacat/trunk metacat</div>
498
      
499
    <p>You should see a list of files as they check out.</p>
500
    
501
    <p>Note that you do not need to create the war file directly with a source installation
502
    since the Ant build file has an "install" target that will build and deploy the war
503
    for you.  See the <a href="#InstallingMetacat">Installing Metacat</a> for instructions.</p>
504

    
505

    
506
<a name="InstallingMetacat"></a><div class="header1">Installing Metacat</div>
507
  <p>This section is only for a new installation. If you are upgrading an existing Metacat, please skip
508
  this section and go to the next one - <a href="#UpgradingMetacat">Upgrading Existing Metacat</a></p>
509
  
510
  <p>Tomcat will look for it's application files (war files) in a configured directory.  
511
  This is typically the &lt;tomcat_home&gt;/webapps directory, but your instance of Tomcat may 
512
  be configured to look in a different directory.  We will refer to your Tomcat application directory 
513
  as &lt;tomcat_app_dir&gt;.</p>
514
     
515
  <a name="CreateMetacatDirs"></a><div class="header2">Create Metacat Directories</div>
516
    <p>Metacat uses a base directory to store such things as store data and metadata,
517
    temporary files and configuration backups.  This directory should be outside of the 
518
    Tomcat application directory since the application directory gets wiped out during an
519
    upgrade. Create the metacat utility base directory 
520
    by typing:</p>
521
      <div class="code">sudo mkdir <metacat_base_dir></div>
522
    <p>(Typically <metacat_base_dir> is '/var/metacat'.)  Remember the directory you 
523
    choose, since you will be asked to configure Metacat to point to it after startup.</p>
524
    
525
    <p>Change the ownership of the directory by typing:</p>   
526
	  <div class="code">sudo chown -R &lt;tomcat_user&gt; /var/metacat</div>
527
    <p>where &lt;tomcat_user&gt; is the user that will start Tomcat.  If you are 
528
	starting Tomcat as the root user, you do not need to run the chown command.</p>
529
	
530
  <a name="InstallMetacatWar"></a><div class="header2">Install Metacat Binary (War)</div> 
531
    <p>Copy the war file to Tomcat:</p>
532
	  <div class="code">sudo cp knb.war &lt;tomcat_app_dir&gt;</div>
533
  
534
  <a name="InstallMetacatSource"></a><div class="header2">Install Metacat From Source</div> 
535
    <p>You will need Apache Ant to do the build.  If you have not already 
536
    installed Ant and you are running Ubuntu/Debian, you can get it by typing:</p>
537
      <div class="code">sudo apt-get install ant</div>
538
  
539
    <p>Otherwise, you can get ant from
540
    <a href="http://ant.apache.org/">The Apache Ant homepage</a></p>
541

    
542
    <p>You should now have the Metacat source in a directory named "metacat" in your
543
    code directory (We will refer to the metacat source directory as &lt;metacat_src_dir&gt;.
544
       
545
    <p>To prepare for the build, edit the file at:</p>
546
      <div class="code">&lt;metacat_src_dir&gt;/build.properties</div> 
547
    <p>Make sure that the "build.tomcat.dir" property is set to your tomcat installation
548
    directory.  For instance:</p>
549
      <div class="code">build.tomcat.dir=/usr/local/tomcat</div>
550
    <p>Metacat will use some of the native Tomcat libraries during the build.</p>
551
    
552
    <p>Make sure that the "app.deploy.dir" property is set to your application deployment
553
    directory.  For instance:</p>
554
      <div class="code">app.deploy.dir=/usr/local/tomcat/webapps</div>
555
    
556
    <p>If your cvs user is something other than the user your are logged in as, you
557
    will need to change the ${env.USER} part of the cvsroot property to be your cvs 
558
    user.  For instance:</p>
559
      <div class="code">cvsroot=:ext:cvs-user@cvs.ecoinformatics.org:/cvs</div>
560
    <p> where your cvs user name is "cvs-user"</p> 
561
    
562
    <p>In the &lt;metacat_src_dir&gt;, run: </p>
563
      <div class="code">ant clean install</div>
564
      
565
    <p>You will see the individual modules get built.  You will be prompted
566
    for your cvs password several times.  You should see a "BUILD SUCCESSFUL"
567
    message at the end.</p>
568
    
569
    <p>You should see a new file named knb.war in your application deployment directory.</div>
570
	  
571
  <a name="ApacheConfig"></a><div class="header2">Configure Apache</div> 
572
    <p>You have the option of running Tomcat stand-alone or with with the Apache web
573
    server.  Running with Apache is the more traditional setup since Apache is a 
574
    more robust web server.  There are some initial setup steps to get Apache talking
575
    to the Metacat application at the </p>
576
	  <a href="./metacat-apache-config.html"> the Metacat Apache Configuration page</a></p>
577

    
578
<a name="UpgradingMetacat"></a><div class="header1">Upgrading Existing Metacat</div>
579
  <a name="protocol"></a>
580
  <p>The following instructions are for upgrading an existing Metacat.
581
  
582
  <a name="UpgradeStopMetacat"></a><div class="header2">Stop the Running Metacat</div>
583
   <p>To do this, login as the user that runs your tomcat server (often "tomcat"),
584
   go to &lt;tomcat_home&gt;/bin and type:</p>
585
   
586
   <div class="code">./shutdown.sh</div>  
587
  
588
  <a name="UpgradeDownloadMetacat"></a><div class="header2">Download Latest Metacat Application</div>
589
    <p>Browse to the 
590
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
591
      In the Metacat section, select the link that looks like:</p>
592
	  <div class="code">metacat-bin-X.X.X.tar.gz</div>
593
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally.</p>
594
    <p>Extract the Metacat package files by typing:</p>
595
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
596
    <p>You should see several files:</p>
597
    
598
    <ul>
599
    <li>knb.war - the Metacat application web archive file.</li>
600
    <li>knb - the web definition file used by Apache on ubuntu/debian Linux systems.</li>
601
    <li>jk.conf - the JkMount configuration file used by Apache on ubuntu/debian Linux systems.</li>
602
    <li>workers.properties - the workers definition file used by Apache on ubuntu/debian Linux systems.</li>
603
    <li>tomcat5.5 - the Tomcat startup script for Tomcat 5.5 installed with apt-get on ubuntu/debian Linux systems.</li>
604
    <li>authority - the optional LSID Server application web archive file.</li>
605
    </ul>
606
    
607
    <p>The location where these files
608
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
609
    of this documentation.</p>
610
 
611
   <a name="UpgradeMetacatWar"></a><div class="header2">Upgrade Metacat Binary (War)</div> 
612
    <p>Tomcat will look for it's application files (war files) in a configured directory.  
613
    This is typically the &lt;tomcat_home&gt;/webapps directory, but your instance of Tomcat may 
614
    be configured to look in a different directory.  We will refer to your Tomcat application directory 
615
    as &lt;tomcat_app_dir&gt;.</p>
616
    
617
    <p>If desired, back up your existing war file with a date:</p>
618
      <div class="code">sudo mv &lt;tomcat_app_dir&gt;/knb.war &lt;tomcat_app_dir&gt;/knb.war.&lt;yyyymmdd&gt;</div>
619
    
620
    <p>Copy the war file to the Tomcat applications directory:</p>
621
	  <div class="code">sudo cp knb.war &lt;tomcat_app_dir&gt;</div>
622
	<p>Remove (or rename) the existing application directory:</p>
623
	  <div class="code">sudo rm -rf &lt;tomcat_home&gt;/webapps/knb</div>
624
	  <p> or </p>
625
	  <div class="code">sudo mv &lt;tomcat_home&gt;/webapps/knb &lt;tomcat_home&gt;/webapps/knb.&lt;yyyymmdd&gt;</div>
626
	<p>Restart Tomcat:</p>  
627
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
628
	<p>Tomcat will expand your war file into a new application directory at startup time.</p>
629
 
630
  <a name="UpgradeMetacatSource"></a><div class="header2">Upgrade Metacat From Source</div>
631
    <p>The steps to upgrade Metacat from source are the same as installing from source.  See
632
    the <a href="#InstallMetacatSource">Install Metacat From Source</a> section above.</p>
633
 
634
  <a name="RestartTomcat"></a><div class="header1">Restart Tomcat</div>
635
    <p>Once you have successfully installed Metacat, there is one more step.  Tomcat
636
    (and Apache if you have Tomcat integrated with it) must be restarted.  To do
637
    this, login as the user that runs your tomcat server (often "tomcat"),
638
    go to &lt;tomcat_home&gt;/bin and type: </p>
639
   
640
      <div class="code">./startup.sh</div>
641
   
642
    <p>In the Tomcat startup messages you should see something in the log file like:</p>
643
   
644
      <div class="code">Metacat: [WARN]: Metacat (1.8.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]</div>
645
     
646
    If you see that message Tomcat has successfully loaded the Metacat servlet.
647
    Next, try to run your new servlet.  Go to a web browser and type:</p>
648
   
649
      <div class="code">http://yourserver.yourdomain.com/yourcontext/</div>
650
     
651
    <p>You should substitute your context name for "yourcontext" in the url above.
652
    If everything is working correctly, you should see a query page followed
653
    by an empty result set.  Note that if you do not have Tomcat integrated with
654
    Apache you will probably have to type</p>
655
   
656
    <div class="code">http://yourserver.yourdomain.com:8080/yourcontext/</div>
657

    
658
  <a name="UpgradeTroubleshooting"></a><div class="header2">Troubleshooting</div>
659
  <p>If you see something like: 
660
  
661
    <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>
662
  
663
  <p>You should add this line: </p>
664
  
665
    <div class="code">JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</div> 
666
    
667
  <p>at the first line of the catalina.sh file in the tomcat bin directory. The reason is that 
668
  GeoServer uses X11 windows to draw graphics.</p>
669
  
670
  <a name="UpgradeConfigureMetacat"></a><div class="header2">Configure Metacat</div>
671
  <p>Once you see the Metacat configuration screen, you can follow the instructions in the 
672
  <a href="./metacat-configure.html"> Configuring Metacat Section</a> 
673
  to complete the internal configuration of Metacat.</p>
674

    
675
<a name="Registry"></a><div class="header1">Web Based Registry</div>
676
  <p>The registry allows users to upload simple metadata documents directly from the web.  See the separate 
677
  <a href="registry_installation.html">Registry Installation Guide</a>.</p><br/><br/>
678
</body>
679
</html>
(27-27/66)