Metacat UNIX Installation Instructions
KNB Home Data People Informatics Biocomplexity Education Software

***Disclaimer***

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.

Pre-Installation

Minimum Requirements

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.

Additional Required Software

The server on which you wish to install Metacat must have the following software installed and running correctly before attempting to install Metacat.

  • Oracle 8i (or another SQL92 compliant RDBMS)
  • Apache Jakarta-Ant
  • Apache Jakarta-Tomcat

    Note: For a more robust web serving environment, Apache web server should be installed along with Tomcat and the two should be integrated as described on the Apache web site.

Aditional Software Setup

Oracle 8i

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: 

lsnrctl start
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.

Ant

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 Should be installed on the system and the "ant" executable shell script should be available in the users path.

Tomcat

Install tomcat into the directory of your choice. The directory in which you install Tomcat itself will be referred to as the "{Tomcat install directory}". This install assumes Tomcat version 3.1. The Tomcat configuration will be slightly different depending on what version of Tomcat you are running.

You must now set up your servlet context. Change to the {Tomcat install directory}/conf. Edit the tomcat.conf file. Find a line that looks like: 

ApJServMount /examples /root
Add the following line below the aforementioned text: 
ApJServMount /metadata /root
Save tomcat.conf.

Edit the server.xml file. Go to the bottom of the file. Find the line that says: 

<Context path="/examples" docbase="/webapps/examples" debug="0" reloadable="true" >
   </Context>
Directly below these lines enter the following: 
<Context path="/metadata" docbase="/opt/tomcat/webapps/metadata" debug="0" reloadable="true" >
   </Context>
Save server.xml.
Note that capital "C" on "Context". This MUST be a capital "C". Also note that "metadata" is an arbitrary servlet name. You may pick whatever servlet name you wish.

After setting up Tomcat, you must make a slight modification to the startup script. Tomcat needs to know about special protocol handlers that Metacat uses for its URLs. Find the line in the tomcat.sh file that says 

    if [ "$TOMCAT_OPTS" = "" ] ; then
     TOMCAT_OPTS=""
    fi
It should be on about line 65. You need to comment out the TOMCAT_OPTS entry that is there and add the following: 
    TOMCAT_OPTS="-Djava.protocol.handler.pkgs=edu.ucsb.nceas.protocols"
When you are done the if statement should look like: 
    if [ "$TOMCAT_OPTS" = "" ] ; then
     #TOMCAT_OPTS=""
     TOMCAT_OPTS="-Djava.protocol.handler.pkgs=edu.ucsb.nceas.protocols"
    fi
You must also complete the protocol.jar step below for this to be completely setup. Also, make sure that this startup script is always used to start tomcat or the parameter will not be set correctly and some features of Metacat will not work.

Your servlet context should now be setup. The next step is giving Tomcat something to run in that context (i.e. Metacat).

Configuring the Server for Metacat

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 CVS system under the module name xmltodb. The command is as follows: 

cvs checkout xmltodb
Or you can download a gzipped tar file from this site.

Once you have either checked out or unzipped and untarred the source distribution, you can begin the installation process. Change into the xmltodb directory and edit the file called "build.xml". The top of a sample build.xml file is shown below. 

      <property name="jdbc-connect" value="jdbc:oracle:thin:@dev.nceas.ucsb.edu:1521:exp"/>
      <property name="installdir" value="/opt/tomcat/webapps/metadata" />
      <property name="name" value="metacat"/>
      <property name="Name" value="MetaCat"/>
      <property name="release" value="1.0a8"/>
      <property name="web-base-url" value="http://www.nceas.ucsb.edu/collab/2840/knbweb"/>
      <property name="replication-path" value="/metadata/servlet/replication"/>
      <property name="servlet-path" value="/metadata/servlet/metacat"/>
      <property name="html-path" value="/metadata"/>
      <property name="image-path" value="/img/metadata" />
      <property name="server" value="dev.nceas.ucsb.edu"/>
      <property name="replication-log" value="metacatreplication.log"/>
      <property name="dataport" value="4444"/>
      <property name="user" value="metadata"/>
      <property name="password" value="your-pw-goes-here"/>

The configuration changes that you need to make are the jdbc-connect, installdir, web-base-url, replication-path, servlet-path, html-path, image-path, server, replication-log, user and password. Each is described below.

  • The jdbc-connect parameter is the JDBC connection string needed to connect to your database. If you are not using Oracle, you will also need to change the name of the JDBC driver in the metacat.properties file.
  • The installdir parameter is the directory that you want Ant to install the servlet to. It is your "servlet context path" that was defined above.
  • Web-base-url is the URL from which you want to load any stylesheets or supplementary images.
  • Replication path is the relative path to the replication servlet. This is should be the name of your servlet followed by "/servlet/replication".
  • 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 
    /<servlet-context-name>/servlet/<servlet-name>
    In the example above "metadata" is the name of the servlet context and "metacat" is the name of the servlet.
  • 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.
  • The image-path is where you want the Metacat image files stored. It should be a directory that is accessible by the web server.
  • Server is the full internet name of the server on which Metacat is running.
  • 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.
  • The user and password parmaters are the Oracle user name that you set up to use Metacat.

Note: DO NOT add a slash [/] to the end of these paths. Metacat will not function correctly if you do so.

Stylesheet Scripts

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. At the SQLPlus prompt type the following: 

@xmltables.sql;
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.

If the script has run correctly you should be able to type 

describe xml_documents
and it should tell you 
    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)

Compilation and Installation

Now we are ready to finish setting up Tomcat by creating the protocol.jar file. To do this, change into the xmltodb directory and type 

ant protocol
When it is done and says "BUILD SUCCESSFUL", change into the 'build' directory. There will be a file there called 'protocol.jar'. Now, copy that file to {tomcat install directory}/lib/protocol.jar. In our case: 
cp protocol.jar /usr/local/devtools/jakarta-tomcat/lib/.
Note that once you have installed the protocol handlers you do not need to install them again. You can recompile Metacat and install it without having to go through this process again.

Once the protocol.jar file is compiled and copied, you are ready to compile and install Metacat. Ant allows compilation and installation to be done in one step. Change into the xmltodb directory and type: 

ant install
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.

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 this go to {Tomcat install directory}/bin and type 

   ./tomcat.sh stop
   ./tomcat.sh start
In the Tomcat startup messages you should see something like: 
    MetacatServlet Initialize
    Context log path="/metadata" :Metacat: init
    MetacatServlet Initialize
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: 
http://yourserver.yourdomain.com/metadata/
If everything is working correctly, you should see a query page followed by a null result set. Note that if you do not have Tomcat integrated with Apache you will probably have to type 
http://yourserver.yourdomain.com:8080/metadata/