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: 2008-07-06 21:25:34 -0700 (Sun, 06 Jul 2008) $'
10
  *    '$Revision: 4080 $'
11
  *
12
  *
13
  -->
14
  
15
<!DOCTYPE html PUBLIC "-//W3C//DTD html 4.0//EN">
16
<html>
17

    
18
<head>
19
  <title>Metacat Installation Instructions</title>
20
  <link rel="stylesheet" type="text/css" href="./default.css">
21
</head>
22

    
23
<body>
24

    
25
<table class="tabledefault" width="100%">
26
<tr><td rowspan="2"><img src="./images/KNBLogo.gif"></td>
27
<td colspan="7">
28
<div class="title">Metacat UNIX Installation Instructions</div>
29
</td>
30
</tr>
31
<tr>
32
  <td><a href="/" class="toollink"> KNB Home </a></td>
33
  <td><a href="/data.html" class="toollink"> Data </a></td>
34
  <td><a href="/people.html" class="toollink"> People </a></td>
35
  <td><a href="/informatics" class="toollink"> Informatics </a></td>
36
  <td><a href="/biodiversity" class="toollink"> Biocomplexity </a></td>
37
  <td><a href="/education" class="toollink"> Education </a></td>
38
  <td><a href="/software" class="toollink"> Software </a></td>
39
</tr>
40
</table>
41
<hr>
42

    
43
<table class="tabledefault" width="100%">
44
<td class="tablehead" colspan="2"><p class="emphasis"><h2>***Disclaimer***</h2></p></td>
45
<tr>
46
<td>
47
  <p class="emphasis">
48
   These installation instructions are meant for a systems administrator/DBA
49
   or someone who is an advanced computer user.  They are NOT meant for
50
   the average computer user.  Please realize that by executing these
51
   instructions, you may have to trouble shoot many advanced issues yourself.
52
</td>
53
</tr>
54
</table>
55

    
56
<table class="tabledefault" width="100%">
57
<td class="tablehead" colspan="2"><p><a name="The Table of Contents"><h2>The Table of Contents</h2></p></td>
58
<tr>
59
<td>
60
  <ul>
61
     <li>
62
         <a HREF="metacatinstall.html#Operating System Specific Instructions">Operating System Specific Instructions</a>
63
      </li>
64
      <li>
65
         <a HREF="metacatinstall.html#Pre-Installation">Pre-Installation</a>
66
      </li>
67
      <li>
68
         <a HREF="metacatinstall.html#Additional Software Setup">Additional Software Setup</a>
69
      </li>
70
      <li>
71
         <a HREF="metacatinstall.html#Installing Metacat">Installing Metacat</a>
72
      </li>
73
        <li>
74
         <a HREF="metacatinstall.html#Upgrade">Upgrading Existing Metacat</a>
75
      </li>
76
      <li>
77
        <a href="metacatinstall.html#Registry">Registry</a>
78
      
79
  </ul>
80
</td>
81

    
82
<table class="tabledefault" width="100%">
83
<td class="tablehead" colspan="2"><p><a name="Operating System Specific Instructions"><h2>Operating System Specific Instructions</h2></p></td>
84
<tr>
85
<td>
86
  <p class="emphasis">
87
These documents are meant to outline the metacat installation process on specific platforms. They are <strong><em>not</em></strong> a substitute for the below instructions and only meant as a supplemental guideline. 
88
  </p>
89
  <ul>
90
    <li> <a href="os_specific/install_metacat_windows.html">Installing from CVS source on Windows XP</a> </li>
91
    <li> <a href="os_specific/install_metacat_ubuntu.html">Installing from CVS source on Ubuntu 6.06 (ie Dapper Drake)</a> </li>
92
    <li> <a href="os_specific/install_metacat_mac.html">Installing from CVS source on Mac OS X</a> </li>
93

    
94
  </ul>
95
</td>
96
</tr>
97
</table>
98

    
99

    
100
<table class="tabledefault" width="100%">
101
<td class="tablehead" colspan="2"><p><a name="Pre-Installation"><h2>Pre-Installation</h2></p></td>
102
<tr>
103
<td>
104
  <p class="header">Minimum Requirements</p> 
105
  <p>
106
   Installing Metacat requires a server running an SQL92 compliant database
107
   (Oracle 8i or Postgresql recommended) with at least 128MB RAM, and a Pentium III class
108
   processor or higher.  The amount of disk space required depends on the
109
   size of your RDBMS tablespace (which should be at least 10 MB, 
110
   however Metacat itself requires only about 1 MB of free space after 
111
   installation).  These instructions assume a Linux environment but may
112
   work on other UNIX type environments, however this has not been tested.
113
  </p>
114
  <p class = "header">Additional Required Software</p>
115
  <p>
116
   The server on which you wish to install Metacat must have the following
117
   software installed and running correctly before attempting to install
118
   Metacat.
119
   <ul>
120
     <li><a href="http://www.oracle.com">Oracle 8i</a> (or another SQL92
121
         compliant RDBMS like Postgres)</li>
122
     <li><a href="http://jakarta.apache.org/ant/index.html">Apache Jakarta-Ant</a>
123
     </li>
124
     <li><a href="http://jakarta.apache.org/tomcat/index.html">Apache Jakarta-Tomcat</a>
125
       <p class="emphasis">Note: For a more robust web serving environment, 
126
       Apache web server should
127
       be installed along with Tomcat and the two should be integrated
128
       as described on the Apache web site.</p>
129
     </li>
130
   </ul>
131
  </p>
132
</td>
133
</tr>
134
</table>
135

    
136
<table class="tabledefault" width="100%">
137
<td class="tablehead" colspan="2"><p><a name="Additional Software Setup"><h2>Aditional Software Setup</h2></p></td>
138
<tr>
139
<td>
140
  <p class="header">Java</p>
141
  <p>You'll need a recent Java SDK; J2SE 1.4.2 or later is required.  The latest metacat release
142
  has been tested most extensively with <a href="http://java.sun.com/j2se/1.5.0/">J2SE 5.0</a>
143
  and this is the recommended version.
144
  Make sure that JAVA_HOME environment variable is properly set and that both
145
  java and javac are on your PATH.
146
  </p>
147
  <p class="header">Oracle 8i or Postgres</p>
148
  <p><i>Oracle:</i><br>
149
   The Oracle RDBMS must be installed and running as a daemon on the system.
150
   In addition the JDBC listener must be enabled.  You can enable it by
151
   logging in as your Oracle user and typing the following:
152
   <pre>lsnrctl start</pre>
153
   Your instance should have a table space of at least 5 MB (10 MB or higher 
154
   recommended).  You should also have a username specific to Metacat
155
   created and enabled.  This user must have most normal permissions 
156
   including CREATE SESSION, CREATE TABLE, CREATE INDEX, CREATE TRIGGER, 
157
   EXECUTE PROCEDURE, EXECUTE TYPE, etc.  If an action is unexplainably 
158
   rejected by Metacat it is probably because the user permissions are not
159
   correctly set.
160
  </p>
161
  <p><i>Postgres:</i><br>
162
  Postgres can be easily installed on most linux distributions and on
163
  Windows (using cygwin) and Mac OS X.  Using Fedora Core or RedHat Linux,
164
  you can install the rpms for postgres and then run 
165
  <code>/etc/init.d/postgresql start</code> in order to start the database. 
166
  On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command
167
  to install postgres: <code>sudo apt-get install postgresql-8.0</code> and 
168
  then run <code>/etc/init.d/postgresql-8.0 start</code> to start.
169
  
170
  This initializes the data files.  You need to do a bit of configuration
171
  to create a database and set up a user account and allow internet access
172
  via jdbc.  See the postgres documentation for this, but here is a quick 
173
  start:
174
  <ul>
175
     <li>Switch to the "postgres" user account and edit "data/pg_hba.conf", adding the following line to the file:<br>
176
     <code>host   metacat  metacat      127.0.0.1         255.255.255.255   password</code><br>
177
     If your host uses IPv6 addresses, you may need this line instead:
178
     <code>host   metacat  metacat      ::1               ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff password</code></li>
179
     <li>If you are using Postgresql pre-8.0, you must edit the "data/postgres.conf" file and uncomment and edit the line
180
     starting with "tcpip_socket" so that it reads 
181
     <code>tcpip_socket = true</code></li>
182
     <li>Run <code>createdb metacat</code> to create a new database</li>
183
     <li>Run <code>psql metacat</code> to log in using the postgres account and create a new "metacat" user account
184
     <ul>
185
        <li>In postgres, run <code>CREATE USER metacat WITH UNENCRYPTED PASSWORD 'apasswordyoulike';</code></li>
186
        <li>This creates a new account called metacat on the database named metacat</li>
187
        <li>Note: there are many ways to do this, so others such as using 
188
        ENCRYPTED passwords will work fine.</li>
189
     </ul>
190
     </li>
191
     <li>Exit the postgres account back to root and restart the postgres 
192
     database with <code>/etc/init.d/postgresql restart</code></li>
193
     <li>Test logging into the postgres db using the metacat account with 
194
     the following command: 
195
     <code>psql -U metacat -W -h localhost metacat</code></li>
196
  </ul>
197
  </p>
198
  <p class="header">Ant</p>
199
  <p>
200
   Ant is a Java based build application similar to Make on UNIX systems.  
201
   It takes in installation parameters from a file in the root installation
202
   directory named "build.xml".  The Metacat CVS module contains a default
203
   build.xml file that may require some modification upon installation.  Ant
204
   should be installed on the system and the "ant" executable shell script 
205
   should be available in the users path. The latest metacat release was tested with 
206
   Ant 1.6.5. <!-- We note that the current build is 
207
   not working with Ant 1.6.x, so you'll need to use an earler version.  We have 
208
   successfully used Ant 1.5.1, 1.5.2, and some earlier versions. -->
209
  </p>
210
  <p class="header">Tomcat</p>
211
  <p>
212
    Install Tomcat into the directory of your choice. The directory in which 
213
    you install Tomcat itself will be referred to as the "$CATALINA_HOME".
214
    We recommend that you install Tomcat version 5.5.  More details about 
215
    Tomcat installation are available <a href=" http://jakarta.apache.org/tomcat/index.html">here</a>.
216
  </p>
217
 </td>
218
</tr>
219
</table>
220

    
221
<table class="tabledefault" width="100%">
222
<td class="tablehead" colspan="2"><p><a name="Installing Metacat"><h2>Installing Metacat</h2></p></td>
223
<tr>
224
<td>
225
  <a name="protocol"></a>
226
  <p>This section is only for a fresh installation. If you are upgrading an existing Metacat, please skip
227
  this section and go to the next one -  <a HREF="metacatinstall.html#Upgrade">Upgrading Existing Metacat</a>
228
  
229
  <h3>Download Metacat application</h3>
230

    
231
  <p>First <a href="/software/download.html">download metacat-1.9.0.tar.gz</a> from this site.</p><br>
232

    
233
  <p>Extract the contents of the tar file in Linux/Mac by typing: </p>
234
  <pre>
235
  <b>
236
  tar-xvzf metacat-1.9.0.tar.gz
237
  </b>
238
  </pre> 
239
 
240
  <h3>Copy war file to Tomcat application directory</h3>
241

    
242
  <p>Copy knb.war to $CATALINA_HOME/webapps</p>
243
  <p>If desired, you can rename the war file to &lt;yourcontext&gt;.war</p>
244

    
245
  <h3>Create Metacat directory</h3>
246
  
247
  <p>Create the Metacat storage directory:</p>
248
  <pre>
249
  <b>
250
  mkdir /var/metacat
251
  </b>
252
  </pre> 
253
  
254
  <p>Change the ownership of the Metacat storage directory to be the user that runs Tomcat:
255
  <pre>
256
  <b>
257
  chown tomcat:tomcat /var/metacat
258
  </b>
259
  </pre></p> 
260

    
261
  <h3>Restart Tomcat</h3>
262
  <p>
263
   Once you have successfully installed Metacat, there is one more step.  Tomcat
264
   (and Apache if you have Tomcat integrated with it) must be restarted.  To do
265
   this, login as the user that runs your tomcat server (often "tomcat"),
266
   go to $CATALINA_HOME/bin and type:
267
   <pre>
268
   <b>
269
   ./shutdown.sh 
270
   ./startup.sh
271
   </b> 
272
   </pre>
273
   In the Tomcat startup messages you should see something in the log file like:
274
   <pre>
275
	Metacat: [WARN]: Metacat (1.8.1) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]
276
   </pre>
277
   If you see that message Tomcat is successfully loading the Metacat servlet.
278
   Next, try to run your new servlet.  Go to a web browser and type:
279
     <pre>
280
     http://yourserver.yourdomain.com/yourcontext/
281
     </pre>
282
   You should substitute your context name for "yourcontext" in the url above.
283
   If everything is working correctly, you should see a Metacat configuration screen.  Note that if you do not have Tomcat integrated with
284
   Apache you will probably have to type
285
     <pre>
286
     http://yourserver.yourdomain.com:8080/yourcontext/
287
     </pre>
288
  </p>
289
  <p><b>Troubleshooting</b>: If you see something like java.lang.InternalError: 
290
  Can't connect to X11 window server using 'yourservanme:0.0' as the value of the DISPLAY variable.
291
  <p>You should add this line: 
292
  <b>JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</b> at the first line of
293
  catalina.sh file in tomcat bin directory. The reason is that GeoServer uses X11 windows to draw graphics.
294
  </p>
295
  
296
  <h3>Configure Metacat</h3>
297
  <p>
298
  Once you see the Metacat configuration screen, you can follow the instructions in the 
299
  <a href="./metacatconfigure.html"> Configuring Metacat Section</a> 
300
  to complete the internal configuration of Metacat.
301
  </p>
302
  
303
  <h3>Deploy wsdl file (Only for EarthGrid-enabled Metacat installation) </h3>
304
  <p>
305
   Once Tomcat is running successfully, there is another step for EarthGrid-enabled Metacat installation. 
306
   In metacat directory, type:
307
   <pre><b>ant deploy-ecogrid</b></pre> 
308
   It will generate wsdl files for EarthGrid services.
309
   </p>
310

    
311
</td>
312
</tr>
313
</table>
314

    
315
<table class="tabledefault" width="100%">
316
<td class="tablehead" colspan="2"><p><a name="Upgrade"><h2>Compilation and Upgrading Existing Metacat</h2></p></td>
317
<tr>
318
<td>
319
  <a name="protocol"></a>
320
  <p>The following instructions are for upgrading an existing Metacat.
321
  <p><h3>Stop the running Metacat</h3>
322
   <P>To do this, login as the user that runs your tomcat server (often "tomcat"),
323
   go to $CATALINA_HOME/bin and type:
324
   <pre><b>./shutdown.sh</b> </pre>
325
  <p>    
326
  <h3>Run Ant Build</h3>
327
  <p>
328
   Ant allows compilation and upgrading to be done in one step.
329
   Change into the metacat directory and type: 
330
   <pre><b>ant clean upgrade</b></pre>
331
   <p>
332
   You should see a bunch of messages telling you the progress of compilation
333
   and installation.  When it is done you should see the message 
334
   BUILD SUCCESSFUL
335
   and you should be returned to a UNIX command prompt.  If you do not see
336
   the message BUILD SUCCESSFUL then there was an error that you need to 
337
   resolve.
338
   This may come up if you are logged in as a user that does not have write
339
   access to one or more of the directories that are listed in the build.xml
340
   file, or if any of the paths to files are not configured correctly in the
341
   "config" target.
342
  </p>
343
  <p>
344
  Note: The 'data' directories that are indicated in the 'datafilepath' and
345
  'inlinedatafilepath' build properties must be writable
346
  by user account under which Tomcat runs or you will not be able to upload 
347
  data files to the system.
348
  </p>
349

    
350
  <p class="header">To install metacat LSID support, adjust the LSID-related
351
    properties in the build.properties files and type:
352
  <p class="header"><b>ant deploy-lsid</b>
353
 
354
  <p><h3>Upgrade SQL Scripts</h3></p>
355
  <P>Note: there is no SQL script that needs to be run when user upgrades the Metacat
356
         from 1.8.0 to 1.8.1 release.</p>
357
  <p>
358
    If you have an existing metacat installation, you should not run the install
359
    script because it will replace all of the older tables with new, empty 
360
    copies of the tables.  Thus you would lose your data!  Instead, you can 
361
    run some upgrade scripts that will change the table structure as needed for
362
    the new version.  If you are skipping versions, run each upgrade script
363
    for the intermediate versions as well.  Currently the upgrade scripts are:
364
   </p>
365
    <ul>
366
      <li>build/src/upgrade-db-to-1.2.sql</li>
367
      <li>build/src/upgrade-db-to-1.3.sql</li>
368
      <li>build/src/upgrade-db-to-1.4.sql</li>
369
      <li>build/src/upgrade-db-to-1.5.sql</li>
370
      <li>build/src/upgrade-db-to-1.6.sql</li>
371
      <li>build/src/upgrade-db-to-1.7.sql</li>
372
      <li>build/src/upgrade-db-to-1.8.sql</li>
373
    </ul>
374
   <p>
375
    For example, if you had an existing metacat 1.5 installation and you were upgrading 
376
    to metacat 1.8, you would need to run three scripts in sequence:
377
    upgrade-db-to-1.6.sql, upgrade-db-to-1.7.sql, and upgrade-db-to-1.8.sql. 
378
    However, if you were starting from a Metacat 1.7
379
    installation, you would only need to run the upgrade-db-to-1.8.sql script.
380
    <em>Be sure to use the version of the scripts from the 'build/src' directory: they
381
    are customized for your installation in that directory.</em>
382
   </p>
383
   <p>
384
    Ant targets exist to do the upgrades, so you can also do the above described upgrade by running:<br />
385
   </p>
386
   <p>
387
	<strong>ant upgrade16</strong><br />
388
	<strong>ant upgrade17</strong><br />
389
	<strong>ant upgrade18</strong><br />
390
   </p>
391

    
392
  </p>
393
  <h3>Restart Tomcat</h3>
394
  <p>
395
   Once you have successfully installed Metacat, there is one more step.  Tomcat
396
   (and Apache if you have Tomcat integrated with it) must be restarted.  To do
397
   this, login as the user that runs your tomcat server (often "tomcat"),
398
   go to $CATALINA_HOME/bin and type:
399
   <pre>
400
   <b>
401
   ./startup.sh
402
   </b> 
403
   </pre>
404
   In the Tomcat startup messages you should see something in the log file like:
405
   <pre>
406
	Metacat: [WARN]: Metacat (1.8.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]
407
   </pre>
408
   If you see that message Tomcat is successfully loading the Metacat servlet.
409
   Next, try to run your new servlet.  Go to a web browser and type:
410
   <pre>http://yourserver.yourdomain.com/yourcontext/</pre>
411
   You should substitute your context name for "yourcontext" in the url above.
412
   If everything is working correctly, you should see a query page followed
413
   by an empty result set.  Note that if you do not have Tomcat integrated with
414
   Apache you will probably have to type
415
   <pre>http://yourserver.yourdomain.com:8080/yourcontext/</pre>
416
  </p>
417
  <p><b>Troubleshooting</b>: If you see something like java.lang.InternalError: 
418
  Can't connect to X11 window server using 'yourservanme:0.0' as the value of the DISPLAY variable.
419
  <p>You should add this line: 
420
  <b>JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</b> at the first line of
421
  catalina.sh file in tomcat bin directory. The reason is that GeoServer uses X11 windows to draw graphics.
422
  </p>
423
  
424
  <h3>Deploy wsdl file (Only for EarthGrid-enabled Metacat installation) </h3>
425
  <p>
426
   Once Tomcat is running successfully, there is another step for EarthGrid-enabled Metacat installation. 
427
   In metacat directory, type:
428
   <pre><b>ant deploy-ecogrid</b></pre> 
429
   It will generate wsdl files for EarthGrid services.
430
   </p>
431

    
432
</td>
433
</tr>
434
</table>
435

    
436
<table class="tabledefault" width="100%">
437
<td class="tablehead" colspan="2"><a name="Registry"><h2>Web-based Registry for Metacat</h2></td>
438
<tr>
439
<td>
440
<p>The registry allows users to upload simple metadata documents directly from the web.  See the separate 
441
<a href="registry_installation.html">Registry Installation Guide</a>.</p><br /><br />
442
</td>
443
</body>
444
</html>
(32-32/57)