Project

General

Profile

1 878 berkley
<!--
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 3019 perry
  *    '$Date$'
10
  *    '$Revision$'
11 878 berkley
  *
12
  *
13
  -->
14
15
<!DOCTYPE html PUBLIC "-//W3C//DTD html 4.0//EN">
16
<html>
17
18
<head>
19 4668 daigle
  <title>Metacat Linux Installation Instructions</title>
20 4556 daigle
  <link rel="stylesheet" type="text/css" href="./common.css">
21 3780 daigle
  <link rel="stylesheet" type="text/css" href="./default.css">
22 878 berkley
</head>
23
24
<body>
25
26
<table class="tabledefault" width="100%">
27 3780 daigle
<tr><td rowspan="2"><img src="./images/KNBLogo.gif"></td>
28 878 berkley
<td colspan="7">
29 4668 daigle
<div class="title">Metacat Linux Installation Instructions</div>
30 878 berkley
</td>
31
</tr>
32
<tr>
33 3660 barteau
  <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 878 berkley
</tr>
41
</table>
42
<hr>
43
44 4556 daigle
<div class="header1">Table of Contents</div>
45
  <div class="toc">
46 4668 daigle
    <div class="toc1"><a href="#QuickInstallation">Quick Installation</a></div>
47
      <div class="toc2"><a href="#DownloadMetacatInstall">Download Metacat Package</a></div>
48
      <div class="toc2"><a href="#CreateDirs">Create Metacat Directories</a></div>
49
      <div class="toc2"><a href="#InstallJava">Install Java</a></div>
50
      <div class="toc2"><a href="#InstallApache">Install Apache</a></div>
51
      <div class="toc2"><a href="#InstallTomcat">Install Tomcat</a></div>
52
      <div class="toc2"><a href="#InstallPostgres">Install PostgreSQL Database</a></div>
53
      <div class="toc2"><a href="#QuickInstallMetacatWar">Install Metacat War</a></div>
54
      <div class="toc2"><a href="#QuickInstallLsidWar">Install LSID War</a></div>
55
      <div class="toc2"><a href="#ConfigureMetacatInstall">Configure Metacat</a></div>
56
    <div class="toc1"><a href="#QuickUpdate">Quick Update</a></div>
57
      <div class="toc2"><a href="#DownloadMetacatUpdate">Download Metacat Package</a></div>
58
      <div class="toc2"><a href="#BackupApplication">Backup Existing Metacat Installation</a></div>
59
      <div class="toc2"><a href="#QuickUpdateMetacatWar">Update Metacat War</a></div>
60
      <div class="toc2"><a href="#QuickUpdateLsidWar">Update LSID War</a></div>
61
      <div class="toc2"><a href="#ConfigureMetacatUpdate">Configure Metacat</a></div>
62 4556 daigle
    <div class="toc1"><a href="#PreInstallation">Pre-Installation</a></div>
63
      <div class="toc2"><a href="#MinRequirements">Minimum Requirements</a></div>
64
      <div class="toc2"><a href="#AdditionalRequiredSoftware">Additional Required Software</a></div>
65
    <div class="toc1"><a href="#AdditionalSoftwareSetup">Additional Software Setup</a></div>
66 4571 daigle
      <div class="toc2"><a href="#AdditionalSoftwareJava">Java</a></div>
67
      <div class="toc2"><a href="#AdditionalSoftwareOracle">Oracle</a></div>
68
      <div class="toc2"><a href="#AdditionalSoftwarePostgres">PostgreSQL</a></div>
69
      <div class="toc2"><a href="#AdditionalSoftwareAnt">Ant</a></div>
70
      <div class="toc2"><a href="#AdditionalSoftwareTomcat">Tomcat</a></div>
71 4637 daigle
    <div class="toc1"><a href="#DownloadingMetacat">Download Metacat and Get War File</a></div>
72
      <div class="toc2"><a href="#DownloadMetacatBinary">Download Metacat Binary and Create War File</a></div>
73
      <div class="toc2"><a href="#DownloadMetacatSource">Download Metacat Source and Create War File</a></div>
74 4556 daigle
    <div class="toc1"><a href="#InstallingMetacat">Installing Metacat</a></div>
75 4637 daigle
      <div class="toc2"><a href="#CreateMetacatDirs">Create Metacat Directories</a></div>
76 4571 daigle
      <div class="toc2"><a href="#InstallMetacatWar">Install Metacat War</a></div>
77 4556 daigle
    <div class="toc1"><a href="#UpgradingMetacat">Upgrading Existing Metacat</a></div>
78 4571 daigle
      <div class="toc2"><a href="#UpgradeStopMetacat">Stop the Running Metacat</a></div>
79
      <div class="toc2"><a href="#UpgradeDownloadMetacat">Download Latest Metacat Application</a></div>
80
      <div class="toc2"><a href="#UpgradeMetacatWar">Upgrade Metacat War</a></div>
81 4637 daigle
   <div class="toc1"><a href="#RestartTomcat">Restart Tomcat</a></div>
82 4571 daigle
      <div class="toc2"><a href="#UpgradeTroubleshooting">Troubleshooting</a></div>
83
      <div class="toc2"><a href="#UpgradeConfigureMetacat">Configure Metacat</a></div>
84
    <div class="toc1"><a href="#Registry">Web Based Registry</a></div>
85 4556 daigle
  </div>
86 3592 tao
87 4668 daigle
<a name="QuickInstallation"></a><div class="header1">Quick Installation</div>
88 4556 daigle
  <p>These are the installation instructions for a system that has Ubuntu 8.04 installed
89
  and has never had Metacat installed on it:</p>
90
91 4668 daigle
  <a name="DownloadMetacatInstall"></a><div class="header2">Download Metacat Package</div>
92
    <ul>
93
    <li>Browse to the
94 4556 daigle
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
95 4668 daigle
      In the Metacat section, select the link that looks like:
96 4556 daigle
	  <div class="code">metacat-bin-X.X.X.tar.gz</div>
97 4668 daigle
    where X.X.X is the latest version of Metacat.  Choose to save the file locally.</li>
98
    <li>Extract the Metacat package files by typing:
99
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div></li>
100
    <li>You should see a war file and several supporting files.  The location where these files
101 4556 daigle
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder
102 4668 daigle
    of this documentation.</li>
103
    </ul>
104 4556 daigle
105 4668 daigle
  <a name="CreateDirs"></a><div class="header2">Create Metacat Directories</div>
106
    <ul>
107
    <li>Create the metacat utility base directory by typing:
108 4556 daigle
      <div class="code">sudo mkdir /var/metacat</div>
109
	  <div class="code">sudo chown -R &lt;tomcat_user&gt; /var/metacat</div>
110 4668 daigle
    where &lt;tomcat_user&gt; is the user that will start Tomcat.  If you are
111
	starting Tomcat as the root user, you do not need to run the chown command.</li>
112
    </ul>
113 3573 barseghian
114 4668 daigle
  <a name="InstallJava"></a><div class="header2">Install Java</div>
115
    <ul>
116
    <li>Install Java by typing:
117
      <div class="code">sudo apt-get install sun-java5-jdk</div></li>
118
	<li>hit "ok" then "yes" for license agreement</li>
119
	</ul>
120 3573 barseghian
121 4668 daigle
  <a name="InstallApache"></a><div class="header2">Install Apache</div>
122
    <ul>
123
    <li>Install Apache and and Mod JK packages by typing:
124
      <div class="code">sudo apt-get install apache2 libapache2-mod-jk</div></li>
125
    <li>Set up Mod JK apache configuration by typing:
126 4556 daigle
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/jk.conf /etc/apache2/mods-available</div>
127 4668 daigle
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/workers.properties /etc/apache2</div></li>
128
    <li>Enable Apache Mod JK by typing:
129 4556 daigle
      <div class="code">sudo a2dismod jk</div>
130 4668 daigle
      <div class="code">sudo a2enmod jk</div></li>
131
    <li>Set up and enable knb (Metacat) site configurations by typing:
132 4556 daigle
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/knb /etc/apache2/sites-available</div>
133 4668 daigle
      <div class="code">sudo a2ensite knb</div></li>
134
    <li>If you want to run an LSID server along with the Metacat server, set up and enable the authority service site
135
      configurations by typing:
136 4571 daigle
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/authority /etc/apache2/sites-available</div>
137 4668 daigle
      <div class="code">sudo a2ensite authority</div></li>
138
    <li>Restart apache to bring in changes by typing:
139
      <div class="code">sudo /etc/init.d/apache2 force-reload</div></li>
140
    </ul>
141 4556 daigle
142 4668 daigle
  <a name="InstallTomcat"></a><div class="header2">Install Tomcat</div>
143
    <ul>
144
    <li>Install Tomcat 5.5 by typing:
145
      <div class="code">sudo sudo apt-get install tomcat5.5</div> </li>
146
    <li>Install Metacat friendly Tomcat startup script by typing:
147 4556 daigle
      <div class="code">sudo /etc/init.d/tomcat5.5 stop</div>
148
      <div class="code">sudo mv /etc/init.d/tomcat5.5 /etc/init.d/tomcat5.5.bak</div>
149
      <div class="code">sudo cp &lt;metacat_package_dir&gt;/tomcat5.5 /etc/init.d/tomcat5.5</div>
150 4668 daigle
      <div class="code">sudo chmod +x /etc/init.d/tomcat5.5</div></li>
151
    </ul>
152
153
  <a name="InstallPostgres"></a><div class="header2">Install PostgreSQL Database</div>
154
    <ul>
155
    <li>Install PostgreSQL by typing:</p>
156
      <div class="code">sudo apt-get install postgresql</div></li>
157
    <li>Change to postgres user:
158
      <div class="code">sudo su - postgres</div></li>
159
    <li>Setup empty Metacat database instance editing the postgreSQL configuration file:
160
      <div class="code">gedit /etc/postgresql/8.3/main/pg_hba.conf</div></li>
161
    and adding the following line:
162
      <div class="code">host metacat metacat 127.0.0.1 255.255.255.255 password</div></li>
163
    <li>Save the file, then create the metacat instance:
164
      <div class="code">createdb metacat</div></li>
165
    <li>Log into postgreSQL by typing:
166 4556 daigle
	  <div class="code">psql metacat</div>
167 4668 daigle
	and create the metacat user by typing at the psql prompt:
168 4556 daigle
	  <div class="code">CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password';</div>
169 4668 daigle
	where your_password is whatever password you would like for the metacat user.</li>
170
	<li>Exit PostgreSQL by typing
171
	  <div class="code">\q</div></li>
172
	<li>Restart the PostgreSQL database to bring in changes:
173
	  <div class="code">/etc/init.d/postgresql-8.3 restart</div></li>
174
	<li>Log out of the postgres user account by typing:
175
	  <div class="code">logout</div></li>
176
	<li>Test the installation and metacat account by typing:
177
	  <div class="code">psql -U metacat -W -h localhost metacat</div></li>
178
	<li>Log back out of postgreSQL:
179
	  <div class="code">\q</div></li>
180
	</ul>
181 4556 daigle
182 4668 daigle
  <a name="QuickInstallMetacatWar"></a><div class="header2">Install Metacat War</div>
183
    <ul>
184
    <li>Copy the war file to Tomcat:
185
	  <div class="code">sudo cp &lt;metacat_package_dir&gt;/knb.war /usr/share/tomcat5.5/webapps</div></li>
186
	<li>Restart Tomcat:
187
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div></li>
188
  	</ul>
189
190
  <a name="QuickInstallLsidWar"></a><div class="header2">Install LSID War</div>
191
    <ul>
192
    <li>If you want to run an LSID server along with the Metacat server, copy the
193
    authority.war file to Tomcat:
194
	  <div class="code">sudo cp &lt;metacat_package_dir&gt;/authority.war /usr/share/tomcat5.5/webapps</div></li>
195
	<li>Restart Tomcat:
196
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div></li>
197
	</ul>
198
199
  <a name="ConfigureMetacatInstall"></a><div class="header2">Configure Metacat</div>
200 4556 daigle
    <p>Refer to the documentation on <a href="./metacatconfigure.html">Metacat Confguration</a>
201
    to complete your installation of Metacat.</p>
202
203 4668 daigle
  <a name="QuickUpdate"></a><div class="header1">Quick Update</div>
204 4556 daigle
  <p>These are the instructions for a system that already has Metacat installed on it,
205
  but needs a Metacat upgrade:</p>
206
207 4668 daigle
  <a name="DownloadMetacatUpdate"></a><div class="header2">Download Metacat Package</div>
208
    <ul>
209
    <li>Browse to the
210 4556 daigle
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
211 4668 daigle
      In the Metacat section, select the link that looks like:
212 4556 daigle
	  <div class="code">metacat-bin-X.X.X.tar.gz</div>
213 4668 daigle
    where X.X.X is the latest version of Metacat.  Choose to save the file locally.</li>
214
    <li>Extract the Metacat package files by typing:
215 4556 daigle
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
216 4668 daigle
    You should see a war file and several supporting files.  The location where these files
217 4556 daigle
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder
218 4668 daigle
    of this documentation.</li>
219
    </ul>
220
221
  <a name="BackupApplication"></a><div class="header2">Backup Existing Metacat Installation</div>
222
    <ul>
223
    <li>To be safe, it is best to backup the existing Metacat installation.  Do so by typing: </p>
224
	  <div class="code">cp &lt;web_app_dir&gt;/knb &lt;web_app_dir&gt;/knb.&lt;yyyymmdd&gt;</div>
225
	  <div class="code">cp &lt;web_app_dir&gt;/knb.war &lt;web_app_dir&gt;/knb.war.&lt;yyyymmdd&gt;</div>
226
	Of course, you can use any backup strategy you like (or none at all).</p>
227
	</ul>
228 4556 daigle
229 4668 daigle
  <a name="QuickUpdateMetacatWar"></a><div class="header2">Update Metacat War</div>
230
    <ul>
231
    <li>Copy the war file to Tomcat:
232
	  <div class="code">sudo cp knb.war /usr/share/tomcat5.5/webapps</div></li>
233
	<li>Restart Tomcat:
234
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div></li>
235
	</ul>
236
237
  <a name="QuickUpdateLsidWar"></a><div class="header2">Update LSID War</div>
238
    <ul>
239
    <li>If you want to run an LSID server along with the Metacat server, copy the
240
    authority.war file to Tomcat:
241
	  <div class="code">sudo cp &lt;metacat_package_dir&gt;/authority.war /usr/share/tomcat5.5/webapps</div></li>
242
	<li>Restart Tomcat:
243
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div></li>
244
	</ul>
245
246
  <a name="ConfigureMetacatUpdate"></a><div class="header2">Configure Metacat</div>
247 4556 daigle
    <p>Refer to the documentation on <a href="./metacatconfigure.html">Metacat Confguration</a>
248
    to complete your installation of Metacat.</p>
249
250
<a name="PreInstallation"></a><div class="header1">Pre-Installation</div>
251
  <a name="MinRequirements"></a><div class="header2">Minimum Requirements</div>
252 878 berkley
  <p>
253
   Installing Metacat requires a server running an SQL92 compliant database
254 3019 perry
   (Oracle 8i or Postgresql recommended) with at least 128MB RAM, and a Pentium III class
255 878 berkley
   processor or higher.  The amount of disk space required depends on the
256
   size of your RDBMS tablespace (which should be at least 10 MB,
257
   however Metacat itself requires only about 1 MB of free space after
258 3214 costa
   installation).  These instructions assume a Linux environment but may
259 878 berkley
   work on other UNIX type environments, however this has not been tested.
260
  </p>
261 4556 daigle
262
  <a name="AdditionalRequiredSoftware"></a><div class="header2">Additional Required Software</div>
263 878 berkley
  <p>
264
   The server on which you wish to install Metacat must have the following
265
   software installed and running correctly before attempting to install
266
   Metacat.
267
   <ul>
268
     <li><a href="http://www.oracle.com">Oracle 8i</a> (or another SQL92
269 932 jones
         compliant RDBMS like Postgres)</li>
270 878 berkley
     <li><a href="http://jakarta.apache.org/ant/index.html">Apache Jakarta-Ant</a>
271
     </li>
272
     <li><a href="http://jakarta.apache.org/tomcat/index.html">Apache Jakarta-Tomcat</a>
273 932 jones
       <p class="emphasis">Note: For a more robust web serving environment,
274
       Apache web server should
275 878 berkley
       be installed along with Tomcat and the two should be integrated
276
       as described on the Apache web site.</p>
277
     </li>
278
   </ul>
279
  </p>
280
281 4571 daigle
<a name="AdditionalSoftwareSetup"></a><div class="header1">Additional Software Setup</div>
282
  <a name="AdditionalSoftwareJava"></a><div class="header2">Java</div>
283 3214 costa
  <p>You'll need a recent Java SDK; J2SE 1.4.2 or later is required.  The latest metacat release
284
  has been tested most extensively with <a href="http://java.sun.com/j2se/1.5.0/">J2SE 5.0</a>
285
  and this is the recommended version.
286 2182 jones
  Make sure that JAVA_HOME environment variable is properly set and that both
287 4637 daigle
  java and javac are on your PATH.
288 2182 jones
  </p>
289 4571 daigle
  <a name="AdditionalSoftwareOracle"></a><div class="header2">Oracle 8i</div>
290
  <p>The Oracle RDBMS must be installed and running as a daemon on the system.
291 878 berkley
   In addition the JDBC listener must be enabled.  You can enable it by
292 4571 daigle
   logging in as your Oracle user and typing the following:</p>
293
294
     <div class="code">lsnrctl start</div>
295
296
   <p>Your instance should have a table space of at least 5 MB (10 MB or higher
297 878 berkley
   recommended).  You should also have a username specific to Metacat
298
   created and enabled.  This user must have most normal permissions
299
   including CREATE SESSION, CREATE TABLE, CREATE INDEX, CREATE TRIGGER,
300
   EXECUTE PROCEDURE, EXECUTE TYPE, etc.  If an action is unexplainably
301
   rejected by Metacat it is probably because the user permissions are not
302 4571 daigle
   correctly set.</p>
303
304
  <a name="AdditionalSoftwarePostgreSQL"></a><div class="header2">PostgreSQL</div>
305
  <p>PostgreSQL can be easily installed on most linux distributions and on
306 2182 jones
  Windows (using cygwin) and Mac OS X.  Using Fedora Core or RedHat Linux,
307 4571 daigle
  you can install the rpms for postgres and then run </p>
308
309
    <div class="code">/etc/init.d/postgresql start</div>
310
311
  <p>in order to start the database.
312 3019 perry
  On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command
313 4637 daigle
  to install postgres:
314
    <div class="code">sudo apt-get install postgresql-8.0</div> and
315
  then run
316
    <div class="code">/etc/init.d/postgresql-8.0 start</div> to start.
317 3019 perry
318 2182 jones
  This initializes the data files.  You need to do a bit of configuration
319
  to create a database and set up a user account and allow internet access
320
  via jdbc.  See the postgres documentation for this, but here is a quick
321
  start:
322
  <ul>
323 4637 daigle
     <li>Switch to the "postgres" user account
324
       <div class="code">sudo su - postgres</div></li>
325
     <li>Edit "data/pg_hba.conf", adding the following line to the file:<br>
326
       <div class="code">host   metacat  metacat      127.0.0.1         255.255.255.255   password</div>
327 3615 bowdish
     If your host uses IPv6 addresses, you may need this line instead:
328 4637 daigle
       <div class="code">host   metacat  metacat      ::1               ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff password</div></li>
329 3019 perry
     <li>If you are using Postgresql pre-8.0, you must edit the "data/postgres.conf" file and uncomment and edit the line
330 2182 jones
     starting with "tcpip_socket" so that it reads
331 4637 daigle
       <div class="code">tcpip_socket = true</div></li>
332
     <li>Create metacat database by typing:
333
       <div class="code">createdb metacat</div></li>
334
     <li>Log in using the postgres account and create a new "metacat" user account by typing:
335
       <div class="code">psql metacat</div>
336 2182 jones
     <ul>
337 4637 daigle
        <li>In postgres, run <div class="code">CREATE USER metacat WITH UNENCRYPTED PASSWORD 'apasswordyoulike';</div></li>
338 2182 jones
        <li>This creates a new account called metacat on the database named metacat</li>
339
        <li>Note: there are many ways to do this, so others such as using
340
        ENCRYPTED passwords will work fine.</li>
341
     </ul>
342
     </li>
343
     <li>Exit the postgres account back to root and restart the postgres
344 4637 daigle
     database by typing:
345
       <div class="code">/etc/init.d/postgresql restart</div></li>
346 2182 jones
     <li>Test logging into the postgres db using the metacat account with
347
     the following command:
348 4637 daigle
       <div class="code">psql -U metacat -W -h localhost metacat</div></li>
349 2182 jones
  </ul>
350
  </p>
351 4571 daigle
352
  <a name="AdditionalSoftwareAnt"></a><div class="header2">Ant</div>
353 878 berkley
  <p>
354
   Ant is a Java based build application similar to Make on UNIX systems.
355
   It takes in installation parameters from a file in the root installation
356
   directory named "build.xml".  The Metacat CVS module contains a default
357
   build.xml file that may require some modification upon installation.  Ant
358 932 jones
   should be installed on the system and the "ant" executable shell script
359 3019 perry
   should be available in the users path. The latest metacat release was tested with
360
   Ant 1.6.5. <!-- We note that the current build is
361 2182 jones
   not working with Ant 1.6.x, so you'll need to use an earler version.  We have
362 3019 perry
   successfully used Ant 1.5.1, 1.5.2, and some earlier versions. -->
363 878 berkley
  </p>
364 4571 daigle
365
  <a name="AdditionalSoftwareTomcat"></a><div class="header2">Tomcat</div>
366 878 berkley
  <p>
367 2302 costa
    Install Tomcat into the directory of your choice. The directory in which
368 4637 daigle
    you install Tomcat itself will be referred to as the &lt;tomcat_home&gt;.
369 4646 daigle
    We recommend that you install Tomcat version 5.5.  If you are running
370
    Ubuntu/Debian, you can get Tomcat by typing:</p>
371
      <div class="code">sudo apt-get install tomcat5.5</div>
372
    Otherwise, you can get Tomcat from <a href=" http://jakarta.apache.org/tomcat/index.html">the Apache Tomcat page</a>.
373 878 berkley
  </p>
374
375 4637 daigle
<a name="DownloadingMetacat"></a><div class="header1">Download Metacat and Get War File</div>
376
 <p>There are several ways to wind up with a Metacat war file, which is needed for
377
 installation.  These are: </p>
378
    <ul>
379
      <li>Download Metacat binary distribution - which will have a pre-built war file.</li>
380
      <li>Download Metacat source distribution - which will then need to be built in order to create a war file.</li>
381
      <li>Download Metacat source from SVN - which will then need to be built in order to create a war file.</li>
382
    </ul>
383
  <p>Since downloading the binary distribution is the easiest and most common install, it
384
  will be discussed here in detail.  Links to source download/build instructions are also
385
  included in case you would like to go that route.</p>
386
  <a name="DownloadMetacatBinary"></a><div class="header2">Download Metacat Binary and Create War File</div>
387
388 4571 daigle
    <p>Browse to the
389
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
390 4637 daigle
      In the Metacat section, for Linux based systems, select the link that looks like:</p>
391 4571 daigle
	  <div class="code">metacat-bin-X.X.X.tar.gz</div>
392 4637 daigle
	  <p>for Windows systems, select the link that looks like:</p>
393
	  <div class="code">metacat-bin-X.X.X.zip</div>
394 4571 daigle
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally.</p>
395 4637 daigle
    <p>Extract the Metacat package files on Linux systems by typing:
396 4571 daigle
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
397 4637 daigle
    <p>or, on Windows, use your system unzip utility to extract the zip file.</p>
398 4571 daigle
    <p>You should see a war file and several supporting files.  The location where these files
399
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder
400
    of this documentation.
401 4637 daigle
402
  <a name="DownloadMetacatSource"></a><div class="header2">Download Metacat Source and Create War File</div>
403
404
    <p>If you would like to download the Metacat source distribution or checkout the source
405
    code from SVN, go to the
406
      <a href="./metacat-source-build.html">Download and Build Metacat From Source</a> page.
407
408
<a name="InstallingMetacat"></a><div class="header1">Installing Metacat</div>
409
  <p>This section is only for a new installation. If you are upgrading an existing Metacat, please skip
410
  this section and go to the next one - <a href="#UpgradingMetacat">Upgrading Existing Metacat</a></p>
411
412
  <p>Tomcat will look for it's application files (war files) in a configured directory.
413
  This is typically the &lt;tomcat_home&gt;/webapps directory, but your instance of Tomcat may
414
  be configured to look in a different directory.  We will refer to your Tomcat application directory
415
  as &lt;tomcat_app_dir&gt;.</p>
416
417
  <a name="CreateMetacatDirs"></a><div class="header2">Create Metacat Directories</div>
418
    <p>Metacat uses a base directory to store such things as store data and metadata,
419
    temporary files and configuration backups.  This directory should be outside of the
420
    Tomcat application directory since the application directory gets wiped out during an
421
    upgrade. Create the metacat utility base directory
422
    by typing:</p>
423
      <div class="code">sudo mkdir <metacat_base_dir></div>
424
    <p>(Typically <metacat_base_dir> is '/var/metacat'.)  Remeber the directory you
425
    choose, since you will be asked to configure Metacat to point to it after startup.</p>
426
427
    <p>Change the ownership of the directory by typing:</p>
428
	  <div class="code">sudo chown -R &lt;tomcat_user&gt; /var/metacat</div>
429
    <p>where &lt;tomcat_user&gt; is the user that will start Tomcat.  If you are
430
	starting Tomcat as the root user, you do not need to run the chown command.</p>
431 4571 daigle
432
  <a name="InstallMetacatWar"></a><div class="header2">Install Metacat War</div>
433
    <p>Copy the war file to Tomcat:</p>
434 4637 daigle
	  <div class="code">sudo cp knb.war &lt;tomcat_app_dir&gt;</div>
435 4646 daigle
436
  <a name="ApacheConfig"></a><div class="header2">Configure Apache</div>
437
    <p>You have the option of running Tomcat stand-alone or with with the Apache web
438
    server.  Running with Apache is the more traditional setup since Apache is a
439
    more robust web server.  There are some initial setup steps to get Apache talking
440
    to the Metacat application at the </p>
441
	  <a href="./metacat-apache-config.html"> the Metacat Apache Configuration page</a></p>
442 3591 costa
443 4571 daigle
<a name="UpgradingMetacat"></a><div class="header1">Upgrading Existing Metacat</div>
444 3593 tao
  <a name="protocol"></a>
445
  <p>The following instructions are for upgrading an existing Metacat.
446 4571 daigle
447
  <a name="UpgradeStopMetacat"></a><div class="header2">Stop the Running Metacat</div>
448
   <p>To do this, login as the user that runs your tomcat server (often "tomcat"),
449 4637 daigle
   go to &lt;tomcat_home&gt;/bin and type:</p>
450 4571 daigle
451
   <div class="code">./shutdown.sh</div>
452
453
  <a name="UpgradeDownloadMetacat"></a><div class="header2">Download Latest Metacat Application</div>
454
    <p>Browse to the
455
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
456
      In the Metacat section, select the link that looks like:</p>
457
	  <div class="code">metacat-bin-X.X.X.tar.gz</div>
458
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally.</p>
459
    <p>Extract the Metacat package files by typing:</p>
460
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
461 4637 daigle
    <p>You should see several files:</p>
462
463
    <ul>
464
    <li>knb.war - the Metacat application web archive file.</li>
465
    <li>knb - the web definition file used by Apache on ubuntu/debian Linux systems.</li>
466
    <li>jk.conf - the JkMount configuration file used by Apache on ubuntu/debian Linux systems.</li>
467
    <li>workers.properties - the workers definition file used by Apache on ubuntu/debian Linux systems.</li>
468
    <li>tomcat5.5 - the Tomcat startup script for Tomcat 5.5 installed with apt-get on ubuntu/debian Linux systems.</li>
469
    <li>authority - the optional LSID Server application web archive file.</li>
470
    </ul>
471
472
    <p>The location where these files
473 4571 daigle
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder
474
    of this documentation.</p>
475 3593 tao
476 4571 daigle
   <a name="UpgradeMetacatWar"></a><div class="header2">Upgrade Metacat War</div>
477 4637 daigle
    <p>Tomcat will look for it's application files (war files) in a configured directory.
478
    This is typically the &lt;tomcat_home&gt;/webapps directory, but your instance of Tomcat may
479
    be configured to look in a different directory.  We will refer to your Tomcat application directory
480
    as &lt;tomcat_app_dir&gt;.</p>
481
482
    <p>If desired, back up your existing war file with a date:</p>
483
      <div class="code">sudo mv &lt;tomcat_app_dir&gt;/knb.war &lt;tomcat_app_dir&gt;/knb.war.&lt;yyyymmdd&gt;</div>
484
485
    <p>Copy the war file to the Tomcat applications directory:</p>
486
	  <div class="code">sudo cp knb.war &lt;tomcat_app_dir&gt;</div>
487 4571 daigle
	<p>Remove (or rename) the existing application directory:</p>
488 4637 daigle
	  <div class="code">sudo rm -rf &lt;tomcat_home&gt;/webapps/knb</div>
489 4571 daigle
	  <p> or </p>
490 4637 daigle
	  <div class="code">sudo mv &lt;tomcat_home&gt;/webapps/knb &lt;tomcat_home&gt;/webapps/knb.&lt;yyyymmdd&gt;</div>
491 4571 daigle
	<p>Restart Tomcat:</p>
492
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
493 4637 daigle
	<p>Tomcat will expand your war file into a new application directory at startup time.</p>
494 4571 daigle
495 4637 daigle
  <a name="RestartTomcat"></a><div class="header1">Restart Tomcat</div>
496 4571 daigle
    <p>Once you have successfully installed Metacat, there is one more step.  Tomcat
497
    (and Apache if you have Tomcat integrated with it) must be restarted.  To do
498
    this, login as the user that runs your tomcat server (often "tomcat"),
499 4637 daigle
    go to &lt;tomcat_home&gt;/bin and type: </p>
500 4571 daigle
501
      <div class="code">./startup.sh</div>
502
503
    <p>In the Tomcat startup messages you should see something in the log file like:</p>
504
505
      <div class="code">Metacat: [WARN]: Metacat (1.8.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]</div>
506
507
    If you see that message Tomcat has successfully loaded the Metacat servlet.
508
    Next, try to run your new servlet.  Go to a web browser and type:</p>
509
510
      <div class="code">http://yourserver.yourdomain.com/yourcontext/</div>
511
512
    <p>You should substitute your context name for "yourcontext" in the url above.
513
    If everything is working correctly, you should see a query page followed
514
    by an empty result set.  Note that if you do not have Tomcat integrated with
515
    Apache you will probably have to type</p>
516
517
    <div class="code">http://yourserver.yourdomain.com:8080/yourcontext/</div>
518 3649 barseghian
519 4571 daigle
  <a name="UpgradeTroubleshooting"></a><div class="header2">Troubleshooting</div>
520
  <p>If you see something like:
521 3520 tao
522 4571 daigle
    <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>
523
524
  <p>You should add this line: </p>
525
526
    <div class="code">JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</div>
527
  <p>at the first line of the catalina.sh file in the tomcat bin directory. The reason is that
528
  GeoServer uses X11 windows to draw graphics.</p>
529
530
  <a name="UpgradeConfigureMetacat"></a><div class="header2">Configure Metacat</div>
531
  <p>Once you see the Metacat configuration screen, you can follow the instructions in the
532
  <a href="./metacatconfigure.html"> Configuring Metacat Section</a>
533
  to complete the internal configuration of Metacat.</p>
534 3066 perry
535 4571 daigle
<a name="Registry"></a><div class="header1">Web Based Registry</div>
536
  <p>The registry allows users to upload simple metadata documents directly from the web.  See the separate
537
  <a href="registry_installation.html">Registry Installation Guide</a>.</p><br/><br/>
538 878 berkley
</body>
539
</html>