/docs/user/metacatinstall.html - Annotate - Metacat - Ecoinformatics Redmine

metacat/docs/user/metacatinstall.html @ 3520

-            berkley
+<!--
   *   '$RCSfile$'
   *     Purpose: web page describing the installation of Metacat
   *   Copyright: 2000 Regents of the University of California and the
   *               National Center for Ecological Analysis and Synthesis
   *     Authors: Chad Berkley
+  *
   *    '$Author$'
-            perry
+  *    '$Date$'
   *    '$Revision$'
             berkley
+  *
   -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD html 4.0//EN">
 <html>
 <head>
   <title>Metacat Installation Instructions</title>
   <link rel="stylesheet" type="text/css" href="@docrooturl@default.css">
 </head>
 <body>
 <table class="tabledefault" width="100%">
 <tr><td rowspan="2"><img src="@docrooturl@images/KNBLogo.gif"></td>
 <td colspan="7">
 <div class="title">Metacat UNIX Installation Instructions</div>
 </td>
 </tr>
 <tr>
   <td><a href="@server@/" class="toollink"> KNB Home </a></td>
   <td><a href="@server@/data.html" class="toollink"> Data </a></td>
   <td><a href="@server@/people.html" class="toollink"> People </a></td>
   <td><a href="@server@/informatics" class="toollink"> Informatics </a></td>
   <td><a href="@server@/biodiversity" class="toollink"> Biocomplexity </a></td>
   <td><a href="@server@/education" class="toollink"> Education </a></td>
   <td><a href="@server@/software" class="toollink"> Software </a></td>
 </tr>
 </table>
 <hr>
 <table class="tabledefault" width="100%">
 <td class="tablehead" colspan="2"><p class="emphasis">***Disclaimer***</p></td>
 <tr>
 <td>
   <p class="emphasis">
-            jones
+   These installation instructions are meant for a systems administrator/DBA
    or someone who is an advanced computer user.  They are NOT meant for
    the average computer user.  Please realize that by executing these
    instructions, you may have to trouble shoot many advanced issues yourself.
-            berkley
+</td>
 </tr>
 </table>
 <table class="tabledefault" width="100%">
 <td class="tablehead" colspan="2"><p>Pre-Installation</p></td>
 <tr>
 <td>
   <p class="header">Minimum Requirements</p>
   <p>
    Installing Metacat requires a server running an SQL92 compliant database
-            perry
+   (Oracle 8i or Postgresql recommended) with at least 128MB RAM, and a Pentium III class
-            berkley
+   processor or higher.  The amount of disk space required depends on the
    size of your RDBMS tablespace (which should be at least 10 MB,
    however Metacat itself requires only about 1 MB of free space after
-            costa
+   installation).  These instructions assume a Linux environment but may
-            berkley
+   work on other UNIX type environments, however this has not been tested.
   </p>
   <p class = "header">Additional Required Software</p>
   <p>
    The server on which you wish to install Metacat must have the following
    software installed and running correctly before attempting to install
    Metacat.
    <ul>
      <li><a href="http://www.oracle.com">Oracle 8i</a> (or another SQL92
-            jones
+         compliant RDBMS like Postgres)</li>
-            berkley
+     <li><a href="http://jakarta.apache.org/ant/index.html">Apache Jakarta-Ant</a>
      </li>
      <li><a href="http://jakarta.apache.org/tomcat/index.html">Apache Jakarta-Tomcat</a>
-            jones
+       <p class="emphasis">Note: For a more robust web serving environment,
        Apache web server should
-            berkley
+       be installed along with Tomcat and the two should be integrated
        as described on the Apache web site.</p>
      </li>
    </ul>
   </p>
 </td>
 </tr>
 </table>
 <table class="tabledefault" width="100%">
 <td class="tablehead" colspan="2"><p>Aditional Software Setup</p></td>
 <tr>
 <td>
-            jones
+  <p class="header">Java</p>
-            costa
+  <p>You'll need a recent Java SDK; J2SE 1.4.2 or later is required.  The latest metacat release
   has been tested most extensively with <a href="http://java.sun.com/j2se/1.5.0/">J2SE 5.0</a>
   and this is the recommended version.
-            jones
+  Make sure that JAVA_HOME environment variable is properly set and that both
   java and javac are on your PATH.
   </p>
   <p class="header">Oracle 8i or Postgres</p>
   <p><i>Oracle:</i><br>
-            berkley
+   The Oracle RDBMS must be installed and running as a daemon on the system.
    In addition the JDBC listener must be enabled.  You can enable it by
    logging in as your Oracle user and typing the following:
    <pre>lsnrctl start</pre>
    Your instance should have a table space of at least 5 MB (10 MB or higher
    recommended).  You should also have a username specific to Metacat
    created and enabled.  This user must have most normal permissions
    including CREATE SESSION, CREATE TABLE, CREATE INDEX, CREATE TRIGGER,
    EXECUTE PROCEDURE, EXECUTE TYPE, etc.  If an action is unexplainably
    rejected by Metacat it is probably because the user permissions are not
    correctly set.
   </p>
-            jones
+  <p><i>Postgres:</i><br>
   Postgres can be easily installed on most linux distributions and on
   Windows (using cygwin) and Mac OS X.  Using Fedora Core or RedHat Linux,
   you can install the rpms for postgres and then run
-            perry
+  <code>/etc/init.d/postgresql start</code> in order to start the database.
   On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command
   to install postgres: <code>sudo apt-get install postgresql-8.0</code> and
   then run <code>/etc/init.d/postgresql-8.0 start</code> to start.
-            jones
+  This initializes the data files.  You need to do a bit of configuration
   to create a database and set up a user account and allow internet access
   via jdbc.  See the postgres documentation for this, but here is a quick
   start:
   <ul>
      <li>Switch to the "postgres" user account and edit "data/pg_hba.conf", adding the following line to the file:<br>
-            jones
+     <code>host   metacat  metacat      127.0.0.1         255.255.255.255   password</code><br>
      If your host uses IPv6 addresses, you made need this line instead:
      <code>host   metacat  metacat      ::1               ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff password</code></li>
-            perry
+     <li>If you are using Postgresql pre-8.0, you must edit the "data/postgres.conf" file and uncomment and edit the line
-            jones
+     starting with "tcpip_socket" so that it reads
      <code>tcpip_socket = true</code></li>
      <li>Run <code>createdb metacat</code> to create a new database</li>
      <li>Run <code>psql metacat</code> to log in using the postgres account and create a new "metacat" user account
      <ul>
         <li>In postgres, run <code>CREATE USER metacat WITH UNENCRYPTED PASSWORD 'apasswordyoulike';</code></li>
         <li>This creates a new account called metacat on the database named metacat</li>
         <li>Note: there are many ways to do this, so others such as using
         ENCRYPTED passwords will work fine.</li>
      </ul>
      </li>
      <li>Exit the postgres account back to root and restart the postgres
      database with <code>/etc/init.d/postgresql restart</code></li>
      <li>Test logging into the postgres db using the metacat account with
      the following command:
      <code>psql -U metacat -W -h localhost metacat</code></li>
   </ul>
   </p>
-            berkley
+  <p class="header">Ant</p>
   <p>
    Ant is a Java based build application similar to Make on UNIX systems.
    It takes in installation parameters from a file in the root installation
    directory named "build.xml".  The Metacat CVS module contains a default
    build.xml file that may require some modification upon installation.  Ant
-            jones
+   should be installed on the system and the "ant" executable shell script
-            perry
+   should be available in the users path. The latest metacat release was tested with
    Ant 1.6.5. <!-- We note that the current build is
-            jones
+   not working with Ant 1.6.x, so you'll need to use an earler version.  We have
-            perry
+   successfully used Ant 1.5.1, 1.5.2, and some earlier versions. -->
-            berkley
+  </p>
   <p class="header">Tomcat</p>
   <p>
-            costa
+    Install Tomcat into the directory of your choice. The directory in which
-            tao
+    you install Tomcat itself will be referred to as the "$CATALINA_HOME".
-            costa
+    We recommend that you install Tomcat version 5.5.  More details about
     Tomcat installation are available <a href=" http://jakarta.apache.org/tomcat/index.html">here</a>.
-            berkley
+  </p>
-            tao
+ </td>
-            berkley
+</tr>
 </table>
 <table class="tabledefault" width="100%">
-            tao
+<td class="tablehead" colspan="2"></td>
-            berkley
+<tr>
 <td>
   <p>
    Once all of the prerequisite software is installed as described above,
    the installation of Metacat can begin.  First you must have a current
    version of the source distribution of Metacat.  You can get it two ways.
    Authorized users can check it out of the NCEAS
    <a href="http://www.nceas.ucsb.edu/cgi-bin/cvsweb.cgi/xmltodb/">CVS</a>
-            jones
+   system. You'll need both the "metacat" module and the "utilities" module to
    be checked out in sibling directories. The command is as follows:
    <pre>mkdir knb-software</pre>
    <pre>cd knb-software</pre>
    <pre>cvs checkout -P metacat</pre>
    <pre>cvs checkout -P utilities</pre>
    Or you can
-            berkley
+   <a href="@server@/software/download.html">download</a> a gzipped tar file
    from this site.
   </p>
   <p>
             costa
   <h2>Edit <code>build.properties</code> File</h2></p>
   <p>
-            berkley
+   Once you have either checked out or unzipped and untarred the source
    distribution, you can begin the installation process.  Change into the
-            costa
+   metacat directory and edit the file called "<code>build.properties</code>".  You will need
-            jones
+   to change a number of configuration properties to match the setup on
-            costa
+   your system.
-            berkley
+  </p>
   <p>
-            costa
+  The properties that you will likely need to change will include:
   <ul>
   <li><code>tomcat</code></li>
   <li><code>deploy.dir</code></li>
-            tao
+  <li><code>tomcatversion</code></li>
-            costa
+  <li><code>metacat.context</code></li>
   <li><code>config.hostname</code></li>
   <li><code>config.port</code></li>
   <li><code>config.port.https</code></li>
   <li><code>ldapUrl</code></li>
   <li><code>database</code></li>
   <li><code>jdbc-connect</code></li>
   <li><code>jdbc-base</code></li>
   <li><code>user</code></li>
   <li><code>password</code></li>
   <li><code>datafilepath</code></li>
   <li><code>inlinedatafilepath</code></li>
   <li><code>default-style</code></li>
   <li><code>administrators</code></li>
   <li><code>authority.context</code></li>
   <li><code>config.lsidauthority</code></li>
   </ul>
   Each is described in detail in the following table:
-            berkley
+  </p>
-            costa
+  <br><br>
   <table border="1">
     <tr>
       <td><b>Property</b></td>
       <td><b>Description</b></td>
       <td><b>Default value and examples of other values</b></td>
     </tr>
     <tr>
       <td>tomcat</td>
       <td>The tomcat property is the location in which tomcat is installed.</td>
       <td>Default:&nbsp;&nbsp;
           <code>/usr/local/devtools/jakarta-tomcat</code>
       <br><br>Example:&nbsp;&nbsp;
-            costa
+          <code>C:/Tomcat-5.5</code></td>
-            costa
+    </tr>
     <tr>
-            costa
+      <td>deploy.dir</td>
       <td>The deploy.dir property is the location in which your tomcat servlet
           contexts are deployed. This is typically "${tomcat}/webapps",
           where ${tomcat} is the same value that you entered for the 'tomcat'
-            costa
+          property above.
       </td>
       <td>Default:&nbsp;&nbsp;
           <code>/var/www/org.ecoinformatics.knb</code>
       <br><br>Example:&nbsp;&nbsp;
-            costa
+          <code>C:/Tomcat-5.5/webapps</code>
-            costa
+      </td>
     </tr>
     <tr>
-            tao
+      <td>tomcatversion</td>
       <td>The tomcatversion property is the version of tomcat in which you
           want Metacat to run. This will determine the location of some
           jar files coming with tomcat.</td>
       <td>Default:&nbsp;&nbsp;
           <code>tomcat5</code>
       <br><br>Example:&nbsp;&nbsp;
           <code>tomcat4</code>
       </td>
     </tr>
     <tr>
-            costa
+      <td>metacat.context</td>
       <td>The metacat.context property is the name of the servlet context in which you
-            costa
+          want Metacat to be installed. This will determine the installation
           directory for the servlet and many of the URLs that are used to access
           the installed Metacat server.</td>
       <td>Default:&nbsp;&nbsp;
           <code>knb</code>
       <br><br>Example:&nbsp;&nbsp;
           <code>mycontext</code>
       </td>
     </tr>
     <tr>
-            costa
+      <td>config.hostname</td>
       <td>The config.hostname property is the hostname of the server on which Metacat is
-            tao
+          running (note that you should not include the 'http://' in the config.hostname
-            costa
+          property).
-            jones
+      </td>
-            costa
+      <td>Default:&nbsp;&nbsp;
          <code>knb.ecoinformatics.org</code>
       <br><br>Example:&nbsp;&nbsp;
-            costa
+         <code>somehost.university.edu</code>
-            costa
+      </td>
     </tr>
     <tr>
-            costa
+      <td>config.port</td>
       <td>The config.port property is the HTTP plain port number that is used to connect to Metacat.
           If Tomcat is running stand-alone, the value will typically be 8080.</td>
-            costa
+      <td>Default:&nbsp;&nbsp;
-            costa
+          <code>80</code>
-            costa
+      <br><br>Example:&nbsp;&nbsp;
-            costa
+          <code>8080</code>
-            costa
+      </td>
     </tr>
     <tr>
-            costa
+      <td>config.port.https</td>
-            costa
+      <td>The config.port.https property is the HTTP secure port number that is used to connect to Metacat,
           generally when replicating documents to and from other Metacat servers.
-            costa
+          If Tomcat is running stand-alone, the value will typically be 8443.</td>
       <td>Default:&nbsp;&nbsp;
-            tao
+          <code>443</code>
-            costa
+      <br><br>Example:&nbsp;&nbsp;
           <code>8443</code>
       </td>
     </tr>
     <tr>
-            costa
+      <td>ldapUrl</td>
-            jones
+      <td>URL to the LDAP server. The LDAP server is used in the default
           authentication module to authenticate and identify users of the
           system.  To participate in the KNB network, you should leave this at
           the default.  But it can be changed if you want to use a
           different directory of users.
       </td>
-            costa
+      <td>Default:&nbsp;&nbsp;
           <code>ldap://ldap.ecoinformatics.org/dc=ecoinformatics,dc=org</code>
       </td>
     </tr>
     <tr>
       <td>database</td>
       <td>Select the database to use for metadata storage.
           Valid values are <code>oracle</code>, <code>postgresql</code>, or
-            costa
+          <code>sqlserver</code>. <em>Note that sqlserver support is minimal and
-            jones
+          probably will not work without substantial changes on your part,
-            costa
+          possibly including code changes.  We have not recently tested on
           sqlserver.</em>
-            costa
+      </td>
       <td>Default:&nbsp;&nbsp;
-            costa
+          <code>postgresql</code>
-            costa
+      <br><br>Other possible values:&nbsp;&nbsp;
-            costa
+          <code>oracle</code>&nbsp;&nbsp;
-            costa
+          <code>sqlserver</code>
       </td>
     </tr>
     <tr>
       <td>jdbc-connect</td>
       <td>The JDBC connection string used to connect to the database.</td>
       <td>Default:&nbsp;&nbsp;
-            costa
+          <code>jdbc-connect=jdbc:postgresql://localhost/metacat</code>
       <br><br>Example:&nbsp;&nbsp;
           <code>jdbc:oracle:thin:@somehost.university.edu:1521:metacat</code>
-            costa
+      </td>
     <tr>
       <td>jdbc-base</td>
-            costa
+      <td>The base directory for locating JDBC jar files. When using the postgresql database, the default setting of './lib' can be used,
           while oracle and sqlserver databases will require a different setting since these jar files are not included in the Metacat
           distribution.</td>
-            costa
+      <td>Default:&nbsp;&nbsp;
-            costa
+          <code>./lib</code>
-            costa
+      <br><br>Example:&nbsp;&nbsp;
-            costa
+          <code>/usr/oracle/jdbc/lib</code><br>
-            costa
+      </td>
     </tr>
     <tr>
       <td>user</td>
-            costa
+      <td>The database user name that you set up to use Metacat.</td>
-            costa
+      <td>Default:&nbsp;&nbsp;
-            costa
+          <code>metacat</code>
-            costa
+      <br><br>Example:&nbsp;&nbsp;
-            costa
+          <code>metacatuser</code>
-            costa
+      </td>
     </tr>
     <tr>
       <td>password</td>
       <td>The database password that you set up to use Metacat.</td>
       <td>Default:&nbsp;&nbsp;
           <code>yourPasswordHere</code>
       <br><br>Example:&nbsp;&nbsp;
           <code>metacat123</code>
       </td>
     </tr>
     <tr>
       <td>datafilepath</td>
-            jones
+      <td>The datafilepath is the directory to store data files.</td>
-            costa
+      <td>Default:&nbsp;&nbsp;
           <code>/var/metacat/data</code>
       <br><br>Example:&nbsp;&nbsp;
-            costa
+          <code>C:/Tomcat-5.5/data/metacat/data</code>
-            costa
+      </td>
     </tr>
     <tr>
       <td>inlinedatafilepath</td>
-            jones
+      <td>The inlinedatafilepath is the directory to store inline data that
           has been extracted from EML documents.</td>
-            costa
+      <td>Default:&nbsp;&nbsp;
           <code>/var/metacat/inline-data</code>
       <br><br>Example:&nbsp;&nbsp;
-            costa
+          <code>C:/Tomcat-5.5/data/metacat/inlinedata</code>
-            costa
+      </td>
     </tr>
     <tr>
       <td>default-style</td>
       <td>The default-style parameter defines the "style-set" that is to be used
           by default when the qformat parameter is missing or set to "html"
-            costa
+          during a query. It is set to "default", which is one of the styles that
-            costa
+          ships with the default metacat distribution. Other possible settings
           are shown in the examples to the right.</td>
       <td>Default:&nbsp;&nbsp;
-            costa
+          <code>default</code>
       <br><br>Examples:<code>esa kepler knb knb2 knp lter ltss nceas nrs obfs pisco specnet</code>
-            costa
+      </td>
     </tr>
-            jones
+    <tr>
       <td>administrators</td>
       <td>The administrators parameter lists the accounts that are allowed to
           perform administrative actions such as rebuilding indices for
-            costa
+          documents. The list can contain more than one account separated
-            jones
+          by colons.</td>
       <td>Default:&nbsp;&nbsp;
           <code>uid=jones,o=NCEAS,dc=ecoinformatics,dc=org</code>
       <br><br>Examples:&nbsp;&nbsp;
           <code>uid=localadmin,o=ucnrs.org</code>
       </td>
     </tr>
             harris
 	<!-- start lsid stuff -->
 	<tr>
       <td>authority.context</td>
       <td>This is the context for the (Life Sciences Identifier) LSID authority.
         LSID support is an optional feature which can be configured to provide
         metacat access to LSID clients. For more information on LSID's see <a href="http://wiki.gbif.org/guidwiki/wikka.php?wakka=LSID">TDWG
         site</a>.</td>
       <td>Default: authority</td>
     </tr>
 	<tr>
       <td>config.lsidauthority</td>
       <td>This is the name of the LSID authority that this metacat should use.
         This authority needs to be defined as SRV record in a DNS.</td>
-            harris
+      <td><p>Default: ecoinformatics.org</p>
         <p>Examples: esa.org or sulphur.ecoinformatics.org</p></td>
-            harris
+    </tr>
-            costa
+  </table>
   <br>
-            berkley
+  <p>
    Note that the build file is preconfigured to install Metacat either using
-            costa
+   Oracle, PostgreSQL, or Microsoft SQL Server as a backend database.
    To change the database system, simply change the value of the 'database'
    property to be the name of the database target that you wish to use
    (either 'oracle', 'postgresql', or 'sqlserver').
-            berkley
+  </p>
-            tao
+  <p>
   If you want to enable EarthGrid web services (including query, put, authentication and identifier interface), you should
   modify the following two properties:
   <pre>
         install.ecogrid=true
         metacat.dir=your-current-metacat-direcotry
   </pre>
   </p>
-            costa
+  Other properties in <code>build.properties</code> that you can (but generally need not) change:<br />
   <br>
   <table border="1">
     <tr>
       <td><b>Property</b></td>
       <td><b>Description</b></td>
       <td><b>Default value and examples of other values</b></td>
     </tr>
     <tr>
-            costa
+      <td>server</td>
       <td>The server property is the hostname and port number of the server that Metacat uses
           for replicating documents to and from other Metacat servers, which should be with the secure (HTTPS) port.
           Since this property is usually composed of the <code>config.hostname</code> and <code>config.port.https</code> properties (described above),
           the default setting can be used in most cases.
       <td>Default:&nbsp;&nbsp;<code>${config.hostname}:${config.port.https}</code>
       </td>
     </tr>
     <tr>
       <td>httpserver</td>
       <td>httpserver is the plain HTTP address and port number that Metacat uses for purposes
           other than replication. Since this property is usually composed of the <code>config.hosthame</code> and <code>config.port</code>
           properties (described above), the default setting can be used in most cases.</td>
       <td>Default:&nbsp;&nbsp;<code>${config.hostname}:${config.port}</code>
       </td>
     </tr>
     <tr>
-            costa
+      <td>inst.cgi.dir</td>
       <td>Installation directory for registry CGI scripts</td>
       <td>Default:&nbsp;&nbsp;
           <code>/var/www/cgi-knb</code>
       </td>
     </tr>
     <tr>
       <td>cgi-prefix</td>
       <td>&nbsp;</td>
       <td>Default:&nbsp;&nbsp;
-            costa
+          <code>http://${httpserver}/cgi-bin</code>
-            costa
+      </td>
     </tr>
     <tr>
-            costa
+      <td>cvsroot</td>
       <td>CVS access to retrieve latest EML. Only used by
           developers in building the release.</td>
       <td>Default:&nbsp;&nbsp;
           <code><pre>:ext:${env.USER}@cvs.ecoinformatics.org:/cvs</pre></code>
           Example:&nbsp;&nbsp;
           <code><pre>:ext:myaccount@cvs.ecoinformatics.org:/cvs</pre></code>
       </td>
     </tr>
     <tr>
-            costa
+      <td>knb-site-url</td>
       <td>This is the URL to the web context root for the knb site.
           It is used for the qformat=knb skin only.</td>
       <td>Default:&nbsp;&nbsp;
           <code>http://knb.ecoinformatics.org</code>
       </td>
     </tr>
     <tr>
-            costa
+      <td>timedreplication</td>
       <td>Determines whether timed replication to other metacat servers is being used.</td>
       <td>Default:&nbsp;&nbsp;
           <code>false</code>
       <br><br>Other possible values:&nbsp;&nbsp;
           <code>true</code>
       </td>
     </tr>
     <tr>
       <td>firsttimedreplication</td>
       <td>The time for starting first timed replication if timedreplication is true.
           (See comments in build.properties file for additional details.)</td>
       <td>Default:&nbsp;&nbsp;
           <code>10:00 PM</code>
           <code>&nbsp;</code>
       </td>
     </tr>
     <tr>
       <td>timedreplicationinterval</td>
       <td>The interval to next timed replication if timedreplication is true.
           The value is in milliseconds and default value is 48 hours.</td>
       <td>Default:&nbsp;&nbsp;
           <code>172800000</code>
           <code>&nbsp;</code>
       </td>
     </tr>
     <tr>
-            costa
+      <td>forcereplicationwaitingtime</td>
       <td>The waiting time before replication is forced to begin after
           uploading a package. The default value should usually suffice.</td>
       <td>Default:&nbsp;&nbsp;
           <code>30000</code>
           <code>&nbsp;</code>
       </td>
     </tr>
   </table>
   <p>
   Metacat has a number of additional settable properties in file
-            costa
+  <code>lib/metacat.properties</code>. Under most circumstances,
-            costa
+  you will not need to modify this file because the properties of interest
   to you can be controlled by editing <code>build.properties</code> as
   described above. To learn more about Metacat's additional properties,
   see <a href="./properties.html">Metacat Properties File</a>.
   </p>
-            berkley
+  <p class="emphasis">
-            costa
+   Note: When setting properties, DO NOT add a trailing slash [/] to the end of any paths that are specified.
    Metacat will not function correctly if you do so.
-            berkley
+  </p>
             jones
 </td>
 </tr>
 </table>
 <table class="tabledefault" width="100%">
 <td class="tablehead" colspan="2"><p><h2>Compilation and Installation</h2></p></td>
 <tr>
 <td>
   <a name="protocol"></a>
   <p>
    Ant allows compilation and installation to be done in one step.
    Change into the metacat directory and type:
    <pre><b>ant install</b></pre>
    or, if you are upgrading an existing installation, type:
    <pre><b>ant clean upgrade</b></pre>
    <p>
    You should see a bunch of messages telling you the progress of compilation
    and installation.  When it is done you should see the message
    BUILD SUCCESSFUL
    and you should be returned to a UNIX command prompt.  If you do not see
    the message BUILD SUCCESSFUL then there was an error that you need to
    resolve.
    This may come up if you are logged in as a user that does not have write
    access to one or more of the directories that are listed in the build.xml
    file, or if any of the paths to files are not configured correctly in the
    "config" target.
   </p>
   <p>
   Note: The 'data' directories that are indicated in the 'datafilepath' and
   'inlinedatafilepath' build properties must be writeable
   by user account under which Tomcat runs or you will not be able to upload
   data files to the system.
   </p>
-            harris
+  <p class="header">To install metacat LSID support, adjust the LSID-related
     properties in the build.properties files and type:
   <p class="header"><b>ant deploy-lsid</b>
   <p class="header">
   <h2>SQL Scripts</h2></p>
-            berkley
+  <p>
-            jones
+   You now need to set up the table structure in your database.  You can do
    either do this using the ant build system, or by manually running the
    scripts using a sql utility.
   </p>
-            jones
+  <p><b>WARNING: Do NOT run this on an existing metacat installation as it
   will delete all of your data.  If you have an existing metacat installation,
   see the instructions for "Upgrading" below.</b></p>
   <p>To run the scripts using ant, type <code>ant installdb</code>.  This does
   not work for postgres, so you'll need to run the xmltables-postgres.sql script
   manually (see next paragraph).
-            jones
+  </p>
   <p>To run the scripts manually, change to the
-            costa
+   metacat/build/src directory.  Then run you RDBMS's SQL utility.  In Oracle it is
-            berkley
+   SQLPlus.  This tutorial assumes an Oracle database so this example is for
    SQLPlus.  Login as the oracle user that was set up for use with Metacat.
-            tao
+   At the SQLPlus prompt type the following: <pre><b>@xmltables.sql;</b></pre>
-            jones
+   For postgres, use a command like:
    <code>psql -U metacat -W -h localhost -f build/src/xmltables-postgres.sql metacat</code>
-            jones
+  </p>
   <p>Either way,
    you should see a bunch of output showing the creation of the Metacat table
-            berkley
+   space. The first time you run this script you will get several errors at the
    beginning saying that you cannot drop a table/index/trigger because it
    does not exist.  This is normal.  Any other errors besides this need to be
-            tao
+   resolved before continuing. The script file name for PostgreSQL is
-            costa
+   xmltables-postgres.sql and for Microsoft SQL server is
-            jones
+   xmltables-sqlserver.sql.
-            berkley
+  </p>
   <p>
    If the script has run correctly you should be able to type
-            jones
+   <pre>describe xml_documents</pre> and it should show:
-            berkley
+   <pre>
     Name            Null?         Type
     --------------  ------------  ----------------
      DOCID          NOT NULL      VARCHAR2(250)
      ROOTNODEID                   NUMBER(20)
      DOCNAME                      VARCHAR2(100)
      DOCTYPE                      VARCHAR2(100)
      DOCTITLE                     VARCHAR2(1000)
      USER_OWNER                   VARCHAR2(100)
      USER_UPDATED                 VARCHAR2(100)
      SERVER_LOCATION              NUMBER(20)
      REV                          NUMBER(10)
      DATE_CREATED                 DATE
      DATE_UPDATED                 DATE
      PUBLIC_ACCESS                NUMBER(1)
      UPDATED                      NUMBER(1)
    </pre>
   </p>
-            jones
+  <p class="header"><h2>Registering schemas and DTDs</h2></p>
   <p>Once the tables have been created, you should also register the Ecological
   Metadata Language (EML) DTDs and schemas. <b>However, note that you should
   NOT do this if you are upgrading an existing installation -- the upgrade
   scripts take care of it for you (see the next section).</b>  If you are
   installing new, you can register the schema documents by running:</p>
   <pre><b>ant register-schemas</b></pre>
   <p>This command registers the EML DTDs' and schemas' location in the
   metacat server.  Your database username and password have to be set correctly
-            jones
+  for this to work.  Also, if for some reason running this script from ant
   does not work, you could instead try running "build/src/loaddtdschema.sql"
   from your sql utility (but be sure to use the version in the 'build' directory
   that has been customized for your installation).
-            jones
+  </p>
-            jones
+  <p class="header"><h2>Upgrading SQL Scripts</h2></p>
   <p>
     If you have an existing metacat installation, you should not run the install
     script because it will replace all of the older tables with new, empty
     copies of the tables.  Thus you would lose your data!  Instead, you can
     run some upgrade scripts that will change the table structure as needed for
     the new version.  If you are skipping versions, run each upgrade script
     for the intermediate versions as well.  Currently the upgrade scripts are:
    </p>
     <ul>
-            jones
+      <li>build/src/upgrade-db-to-1.2.sql</li>
       <li>build/src/upgrade-db-to-1.3.sql</li>
       <li>build/src/upgrade-db-to-1.4.sql</li>
-            costa
+      <li>build/src/upgrade-db-to-1.5.sql</li>
-            costa
+      <li>build/src/upgrade-db-to-1.6.sql</li>
       <li>build/src/upgrade-db-to-1.7.sql</li>
-            tao
+      <li>build/src/upgrade-db-to-1.7.1.sql</li>
-            jones
+    </ul>
    <p>
-            costa
+    For example, if you had an existing metacat 1.4 installation and you were upgrading
     to metacat 1.7, you would need to run three scripts in sequence:
     upgrade-db-to-1.5.sql, upgrade-db-to-1.6.sql, and upgrade-db-to-1.7.sql.
     However, if you were starting from a Metacat 1.6
     installation, you would only need to run the upgrade-db-to-1.7.sql script.
     <em>Be sure to use the version of the scripts from the 'build/src' directory: they
     are customized for your installation in that directory.</em>
-            jones
+   </p>
   </p>
-            tao
+  <h2>Restart Tomcat</h2>
-            tao
+  <p>
-            berkley
+   Once you have successfully installed Metacat, there is one more step.  Tomcat
    (and Apache if you have Tomcat integrated with it) must be restarted.  To do
-            tao
+   this, login as the user that runs your tomcat server (often "tomcat"),
    go to $CATALINA_HOME/bin and type:
-            berkley
+   <pre>
-            tao
+   ./shutdown.sh
    ./startup.sh
-            berkley
+   </pre>
-            tao
+   In the Tomcat startup messages you should see something in log file like:
-            berkley
+   <pre>
     MetacatServlet Initialize
     Context log path="/metadata" :Metacat: init
     MetacatServlet Initialize
    </pre>
    If you see that message Tomcat is successfully loading the Metacat servlet.
    Next, try to run your new servlet.  Go to a web browser and type:
-            jones
+   <pre>http://yourserver.yourdomain.com/yourcontext/</pre>
    You should substitute your context name for "yourcontext" in the url above.
-            berkley
+   If everything is working correctly, you should see a query page followed
-            jones
+   by an empty result set.  Note that if you do not have Tomcat integrated with
-            berkley
+   Apache you will probably have to type
-            jones
+   <pre>http://yourserver.yourdomain.com:8080/yourcontext/</pre>
-            berkley
+  </p>
-            tao
+  <p><b>Troubleshooting</b>: If you see something like java.lang.InternalError:
   Can't connect to X11 window server using 'yourservanme:0.0' as the value of the DISPLAY variable.
   <p>You should add this line:
   <b>JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</b> at the first line of
-            costa
+  catalina.sh file in tomcat bin directory. The reason is that GeoServer uses X11 windows to draw graphics.
-            tao
+  </p>
             tao
   <h2>Deploy wsdl file (Only for EarthGrid-enabled Metacat installation) </h2>
   <p>
    Once Tomcat is running successfully, there is another step for EarthGrid-enabled Metacat installation.
    In metacat directory, type:
    <pre><b>ant deploy-ecogrid</b></pre>
    It will generate wsdl files for EarthGrid services.
    </p>
             perry
   <h2> Operating System Specific Instructions </h2>
   <p> These documents are meant to outline the metacat installation process on specific platforms. They are <strong><em>not</em></strong> a substitute for the above instructions and only meant as a supplemental guideline. </p>
   <ul>
     <li> <a href="os_specific/install_metacat_windows.txt">Installing from CVS source on Windows XP</a> </li>
-            perry
+    <li> <a href="os_specific/install_metacat_ubuntu.txt">Installing from CVS source on Ubuntu 6.06 (ie Dapper Drake)</a> </li>
     <li> <a href="os_specific/install_metacat_mac.txt">Installing from CVS source on Mac OSX (Intel)</a> </li>
-            perry
+  </ul>
-            berkley
+</td>
 </tr>
 </table>
 </body>
 </html>

Project

General

Profile

Metacat