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

metacat/docs/user/metacatinstall.html @ 994

-            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$'
   *      '$Date$'
   *  '$Revision$'
+  *
+  *
   -->
 <!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
    (Oracle 8i recommended) with at least 128MB RAM, and a Pentium III class
    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
    installation.  These instructions assume a Linux environment but may
    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>
   <p class="header">Oracle 8i</p>
   <p>
    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>
   <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
-            berkley
+   should be available in the users path.
   </p>
   <p class="header">Tomcat</p>
   <p>
     Install tomcat into the directory of your choice. The directory in which
-            jones
+    you install Tomcat itself will be referred to as the "$TOMCAT_HOME".
     This install assumes Tomcat version 3.1.  The Tomcat
     configuration will be slightly different depending on what version of
     Tomcat you are running.
-            berkley
+  </p>
   <p>
-            jones
+    You must now set up your servlet context.  Change to the $TOMCAT_HOME/conf.
     Edit the tomcat.conf file.  Find a line that looks like:
-            berkley
+    <pre>ApJServMount /examples /root</pre>
     Add the following line below the aforementioned text:
     <pre>ApJServMount /metadata /root</pre>
     Save tomcat.conf.
   </p>
   <p>
    Edit the server.xml file.  Go to the bottom of the file.  Find the line that
    says:
    <pre>&lt;Context path="/examples" docbase="/webapps/examples" debug="0" reloadable="true" &gt;
    &lt;/Context&gt;</pre>
    Directly below these lines enter the following:
    <pre>&lt;Context path="/metadata" docbase="/opt/tomcat/webapps/metadata" debug="0" reloadable="true" &gt;
    &lt;/Context&gt;</pre>
    Save server.xml.
    <div class="emphasis">Note that capital "C" on "Context".  This MUST be a
    capital "C".  Also note that "metadata" is an arbitrary servlet name.  You
-            jones
+   may pick whatever servlet name you wish. Also note that the path to the
    servlet context will depend on where you install the tomcat webapps
    directory.</div>
-            berkley
+  </p>
 </td>
 </tr>
 </table>
 <table class="tabledefault" width="100%">
 <td class="tablehead" colspan="2"><p>Configuring the Server for Metacat</p></td>
 <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>
    system under the module name xmltodb.  The command is as follows:
-            jones
+   <pre>cvs checkout -P xmltodb</pre>  Or you can
-            berkley
+   <a href="@server@/software/download.html">download</a> a gzipped tar file
    from this site.
   </p>
   <p>
    Once you have either checked out or unzipped and untarred the source
    distribution, you can begin the installation process.  Change into the
-            jones
+   xmltodb directory and edit the file called "build.xml".  You will need
    to change a number of configuration properties to match the setup on
    your system.  If you are using oracle, you'll need to customize the
    properties in the "oracle" target.  If you are using Postgres, you'll
-            berkley
+   need to customize the properties in the "postgres" target.  All users
-            jones
+   will need to customize the properties in the "config" target.
-            berkley
+  </p>
   <p>
-            jones
+   The properties that you need to change will include jdbc-connect,
-            tao
+   dbDriver, dbAdapter, oracle_home,
-            berkley
+   jdbc, tomcat, webapps, context, user, server, systemidserver,
-            tao
+   web-base-url, and default-style. Each is described in detail below.
    You should also verify that the jar file properties mentioned in the
    remainder of the config target are accessible at the paths listed -- the
    defaults will usually work.
-            berkley
+  </p>
-            berkley
+  <p>
    Note that the build file is preconfigured to install Metacat either using
    Oracle or PostgreSQL as a backend database.  To change the database
    system, simply change the 'depends' attribute of the 'config' target to be
    the name of the database target that you wish to use (either 'oracle' or
    'postgresql').  If you wish to use a different database system, add a new
    target for your database with the needed parameters and actions then add it
    to the 'depends' attribute.
   </p>
-            jones
+  Properties you will likely need to change:<br />
-            berkley
+  <ul>
   <li>
    The jdbc-connect parameter is the JDBC connection string needed to connect
-            jones
+   to your database.
-            berkley
+  </li>
   <li>
-            jones
+   The dbDriver parameter is the name of the JDBC driver class to use for
-            berkley
+   connections to your database.
-            jones
+  </li>
   <li>
-            jones
+   The dbAdapter parameter is the name of the Metacat adapter class to be used
    to communicate with a particular database.
-            berkley
+  </li>
   <li>
-            jones
+   The oracle_home parameter is the location that oracle is installed on
    your system.
   </li>
   <li>
    The jdbc parameter is the location of your jdbc driver jar file.
   </li>
   <li>
    The tomcat parameter is the location in which tomcat is installed.
   </li>
   <li>
    The webapps parameter is the location in which your tomcat servlet
    contexts are installed.  This is typically "$TOMCAT_HOME/webapps".
   </li>
   <li>
    The context parameter is the name of the servlet context in which
    you 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.
   </li>
   <li>
-            jones
+   Web-base-url is the URL from which you want to load any stylesheets
    or supplementary images.
-            berkley
+  </li>
   <li>
-            berkley
+   Server is the http address on which Metacat is running (note that you should
-            tao
+   not include the 'http://' in the server property).
-            jones
+  </li>
-            tao
+  </li>
-            jones
+  <li>
-            tao
+   The systemidserver is the protocol (http or https) and server location to get
-            berkley
+   any DTDs.
-            tao
+  </li>
   <li>
-            berkley
+   The user and password parameters are the database user name that you set up
-            jones
+   to use Metacat, for example an Oracle username and password.
   </li>
   <li>
    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" during
    a query.  It is set to "knb", which is the only style that ships with the
    default metacat distribution.  If you create your own stylesheets for
    displaying metacat output, you may want to create a new config file in the
    config-dir (e.g., mystyle.xml) and then change the default-style to use
    your custom style (e.g., "mystyle").
   </li>
   </ul>
   Other properties that you can but generaly need not change:<br />
   <ul>
   <li>
    The installdir
-            berkley
+   parameter is the directory in which Ant should install the servlet.
-            jones
+   It is your "servlet context path" that was defined above.
   </li>
   <li>
-            jones
+   Replication path is the relative path to the replication servlet.  This
-            berkley
+   should be the name of your servlet followed by "/servlet/replication".  For
    example 'metacat/servlet/replication'.
-            berkley
+  </li>
   <li>
    The servlet path is the relative path to your servlet as viewed by the
    Tomcat or Apache web server.  Under Tomcat, the form is usually
-            tao
+   <pre>/&lt;servlet-context-name&gt;/servlet/metacat</pre>
-            berkley
+  </li>
   <li>
    The html-path is usually the first directory of the servlet-path. The only
    reason it wouldn't be is if you are doing something with your web server
    and you want the html served from a different location than where the
    servlet is located.
   </li>
   <li>
    The image-path is where you want the Metacat image files stored.  It
    should be a directory that is accessible by the web server.
   </li>
   <li>
    Replication-log is the location at which you want Metacat to place any
    replication log files.  The user that starts Tomcat must have permission to
    write to this directory.
   </li>
   <li>
-            jones
+   The config-dir parameter specifies the location of the configuration files
    for the "style-sets" feature.  It is set by default to the installation
    directory and generally does not need to be changed.
   </li>
   <li>
    The eml-module, eml-version, eml-tag parameters control the installation
    behavior with respect to EML.  You should not need to change these paramters.
   </li>
   <li>
    The cvsrootparameter is used when building the distribution and you should
    not need to change it.
   </li>
-            berkley
+  </ul>
   <p class="emphasis">
    Note: DO NOT add a slash [/] to the end of these paths.  Metacat will not
    function correctly if you do so.
   </p>
   <p class="header">Stylesheet Scripts</p>
   <p>
    You now need to set up the table structure in your database.  Change to the
    xmltodb/src directory.  Then run you RDBMS's SQL utility.  In Oracle it is
    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.
-            jones
+   At the SQLPlus prompt type the following: <pre>@src/xmltables.sql;</pre>
-            berkley
+   You should see a bunch of output showing the creation of the Metacat table
    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
    resolved before continuing.
   </p>
   <p>
    If the script has run correctly you should be able to type
    <pre>describe xml_documents</pre> and it should tell you
    <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>
 </td>
 </tr>
 </table>
 <table class="tabledefault" width="100%">
 <td class="tablehead" colspan="2"><p>Compilation and Installation</p></td>
 <tr>
 <td>
   <a name="protocol"></a>
   <p>
-            tao
+   Now we are ready to finish setting up Tomcat by getting DTD file from CVS.
    To do this, change into the xmltodb directory and type
    <pre>ant getdtd</pre>
    When it is done and says "BUILD SUCCESSFUL", the DTD files in CVS server will
    copy to xmltodb/lib/dtd directory.
-            berkley
+  </p>
   <p>
-            tao
+   Once the DTD files are copied, you are ready to compile
-            berkley
+   and install
    Metacat.  Ant allows compilation and installation to be done in one step.
    Change into the xmltodb directory and type:
    <pre>ant install</pre>
    You should see a bunch of messages telling you the progress of compilation
-            jones
+   and installation.  When it is done you should see the message
    BUILD SUCCESSFUL
-            berkley
+   and you should be returned to a UNIX command prompt.  If you do not see
-            jones
+   the message BUILD SUCCESSFUL then there was an error that you need to
    resolve.
-            berkley
+   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
-            jones
+   file, or if any of the paths to files are not configured correctly in the
    "config" target.
-            berkley
+  </p>
-            jones
+  <p>Once metacat itself is installed, you should also register
-            jones
+  the Ecological Metadata Language (EML) DTDs. This process is done most
-            jones
+  easily by running "ant dtdsql" which registers the DTDs with the
-            jones
+  metacat server.  Your database username and password have to be set correctly
   for this to work.
-            tao
+  </p>
-            berkley
+  <p>
-            berkley
+  Note: The 'data' directory in the installation directory must be writeable
   by whatever user is running Tomcat or you will not be able to upload data
   files to the system.
-            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
-            jones
+   this, login as the user that runs your tomcat server (ofter "tomcat"),
    go to $TOMCAT_HOME/bin and type:
-            berkley
+   <pre>
    ./tomcat.sh stop
    ./tomcat.sh start
    </pre>
    In the Tomcat startup messages you should see something like:
    <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>
 </td>
 </tr>
 </table>
 </body>
 </html>

Project

General

Profile

Metacat