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
  <title>Metacat 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
<div class="title">Metacat UNIX Installation Instructions</div>
30
</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
    <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 4571 daigle
      <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 4637 daigle
    <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 4556 daigle
    <div class="toc1"><a href="#InstallingMetacat">Installing Metacat</a></div>
62 4637 daigle
      <div class="toc2"><a href="#CreateMetacatDirs">Create Metacat Directories</a></div>
63 4571 daigle
      <div class="toc2"><a href="#InstallMetacatWar">Install Metacat War</a></div>
64 4556 daigle
    <div class="toc1"><a href="#UpgradingMetacat">Upgrading Existing Metacat</a></div>
65 4571 daigle
      <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 4637 daigle
   <div class="toc1"><a href="#RestartTomcat">Restart Tomcat</a></div>
69 4571 daigle
      <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 4637 daigle
<!--
73 4621 daigle
    <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 4637 daigle
-->
76 4556 daigle
  </div>
77 3592 tao
78 4556 daigle
<a name="QuickInstructions"></a><div class="header1">Quick Instructions</div>
79 3573 barseghian
80 4556 daigle
  <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 4637 daigle
    <a name="CreateDirs"></a><div class="header3">Create Metacat Directories</div>
100 4556 daigle
    <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 3573 barseghian
107 4556 daigle
  <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 3573 barseghian
114 4556 daigle
  <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 4599 walbridge
      <div class="code">sudo apt-get install apache2 libapache2-mod-jk</div>
118
    <p>Set up Mod JK apache configuration by typing:</p>
119 4556 daigle
      <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 4575 daigle
    <p>If you want to run an LSID server along with the Metacat server, set up and enable the authority service site
128 4571 daigle
      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 4556 daigle
    <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 4563 daigle
	<p>Log back out of postgreSQL:</p>
173 4556 daigle
	  <div class="code">\q</div>
174
  </div>
175
176
  <div class=indent>
177 4575 daigle
    <a name="QuickInstallMetacatWar"></a><div class="header3">Install Metacat War</div>
178 4556 daigle
    <p>Copy the war file to Tomcat:</p>
179 4575 daigle
	  <div class="code">sudo cp &lt;metacat_package_dir&gt;/knb.war /usr/share/tomcat5.5/webapps</div>
180 4556 daigle
	<p>Restart Tomcat:</p>
181
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
182
  </div>
183 4575 daigle
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 4556 daigle
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 4637 daigle
	  <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 4556 daigle
	<p>Of course, you can use any backup strategy you like (or none at all).</p>
223
  </div>
224
225
    <div class=indent>
226 4575 daigle
    <a name="QuickUpdateMetacatWar"></a><div class="header3">Install Metacat War</div>
227 4556 daigle
    <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 4575 daigle
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 4556 daigle
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 4637 daigle
<!--
249 4556 daigle
<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 4637 daigle
-->
259 4556 daigle
260
<a name="PreInstallation"></a><div class="header1">Pre-Installation</div>
261
  <a name="MinRequirements"></a><div class="header2">Minimum Requirements</div>
262 878 berkley
  <p>
263
   Installing Metacat requires a server running an SQL92 compliant database
264 3019 perry
   (Oracle 8i or Postgresql recommended) with at least 128MB RAM, and a Pentium III class
265 878 berkley
   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 3214 costa
   installation).  These instructions assume a Linux environment but may
269 878 berkley
   work on other UNIX type environments, however this has not been tested.
270
  </p>
271 4556 daigle
272
  <a name="AdditionalRequiredSoftware"></a><div class="header2">Additional Required Software</div>
273 878 berkley
  <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 932 jones
         compliant RDBMS like Postgres)</li>
280 878 berkley
     <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 932 jones
       <p class="emphasis">Note: For a more robust web serving environment,
284
       Apache web server should
285 878 berkley
       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 4571 daigle
<a name="AdditionalSoftwareSetup"></a><div class="header1">Additional Software Setup</div>
292
  <a name="AdditionalSoftwareJava"></a><div class="header2">Java</div>
293 3214 costa
  <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 2182 jones
  Make sure that JAVA_HOME environment variable is properly set and that both
297 4637 daigle
  java and javac are on your PATH.
298 2182 jones
  </p>
299 4571 daigle
  <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 878 berkley
   In addition the JDBC listener must be enabled.  You can enable it by
302 4571 daigle
   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 878 berkley
   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 4571 daigle
   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 2182 jones
  Windows (using cygwin) and Mac OS X.  Using Fedora Core or RedHat Linux,
317 4571 daigle
  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 3019 perry
  On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command
323 4637 daigle
  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 3019 perry
328 2182 jones
  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 4637 daigle
     <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 3615 bowdish
     If your host uses IPv6 addresses, you may need this line instead:
338 4637 daigle
       <div class="code">host   metacat  metacat      ::1               ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff password</div></li>
339 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
340 2182 jones
     starting with "tcpip_socket" so that it reads
341 4637 daigle
       <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 2182 jones
     <ul>
347 4637 daigle
        <li>In postgres, run <div class="code">CREATE USER metacat WITH UNENCRYPTED PASSWORD 'apasswordyoulike';</div></li>
348 2182 jones
        <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 4637 daigle
     database by typing:
355
       <div class="code">/etc/init.d/postgresql restart</div></li>
356 2182 jones
     <li>Test logging into the postgres db using the metacat account with
357
     the following command:
358 4637 daigle
       <div class="code">psql -U metacat -W -h localhost metacat</div></li>
359 2182 jones
  </ul>
360
  </p>
361 4571 daigle
362
  <a name="AdditionalSoftwareAnt"></a><div class="header2">Ant</div>
363 878 berkley
  <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 932 jones
   should be installed on the system and the "ant" executable shell script
369 3019 perry
   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 2182 jones
   not working with Ant 1.6.x, so you'll need to use an earler version.  We have
372 3019 perry
   successfully used Ant 1.5.1, 1.5.2, and some earlier versions. -->
373 878 berkley
  </p>
374 4571 daigle
375
  <a name="AdditionalSoftwareTomcat"></a><div class="header2">Tomcat</div>
376 878 berkley
  <p>
377 2302 costa
    Install Tomcat into the directory of your choice. The directory in which
378 4637 daigle
    you install Tomcat itself will be referred to as the &lt;tomcat_home&gt;.
379 3214 costa
    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 878 berkley
  </p>
382
383 4637 daigle
<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 4571 daigle
    <p>Browse to the
397
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
398 4637 daigle
      In the Metacat section, for Linux based systems, select the link that looks like:</p>
399 4571 daigle
	  <div class="code">metacat-bin-X.X.X.tar.gz</div>
400 4637 daigle
	  <p>for Windows systems, select the link that looks like:</p>
401
	  <div class="code">metacat-bin-X.X.X.zip</div>
402 4571 daigle
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally.</p>
403 4637 daigle
    <p>Extract the Metacat package files on Linux systems by typing:
404 4571 daigle
      <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
405 4637 daigle
    <p>or, on Windows, use your system unzip utility to extract the zip file.</p>
406 4571 daigle
    <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 4637 daigle
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 4571 daigle
440
  <a name="InstallMetacatWar"></a><div class="header2">Install Metacat War</div>
441
    <p>Copy the war file to Tomcat:</p>
442 4637 daigle
	  <div class="code">sudo cp knb.war &lt;tomcat_app_dir&gt;</div>
443 3591 costa
444 4571 daigle
<a name="UpgradingMetacat"></a><div class="header1">Upgrading Existing Metacat</div>
445 3593 tao
  <a name="protocol"></a>
446
  <p>The following instructions are for upgrading an existing Metacat.
447 4571 daigle
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 4637 daigle
   go to &lt;tomcat_home&gt;/bin and type:</p>
451 4571 daigle
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 4637 daigle
    <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 4571 daigle
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder
475
    of this documentation.</p>
476 3593 tao
477 4571 daigle
   <a name="UpgradeMetacatWar"></a><div class="header2">Upgrade Metacat War</div>
478 4637 daigle
    <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 4571 daigle
	<p>Remove (or rename) the existing application directory:</p>
489 4637 daigle
	  <div class="code">sudo rm -rf &lt;tomcat_home&gt;/webapps/knb</div>
490 4571 daigle
	  <p> or </p>
491 4637 daigle
	  <div class="code">sudo mv &lt;tomcat_home&gt;/webapps/knb &lt;tomcat_home&gt;/webapps/knb.&lt;yyyymmdd&gt;</div>
492 4571 daigle
	<p>Restart Tomcat:</p>
493
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
494 4637 daigle
	<p>Tomcat will expand your war file into a new application directory at startup time.</p>
495 4571 daigle
496 4637 daigle
  <a name="RestartTomcat"></a><div class="header1">Restart Tomcat</div>
497 4571 daigle
    <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 4637 daigle
    go to &lt;tomcat_home&gt;/bin and type: </p>
501 4571 daigle
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 3649 barseghian
520 4571 daigle
  <a name="UpgradeTroubleshooting"></a><div class="header2">Troubleshooting</div>
521
  <p>If you see something like:
522 3520 tao
523 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>
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 3066 perry
536 4571 daigle
<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 878 berkley
</body>
540
</html>