Metacat Installation Instructions

	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

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.

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 like Postgres)
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

You'll need a recent Java SDK; j2sdk1.4.2 or later is required. We haven't tested with any of the 1.5.x versions yet, so probably best to stay with 1.4.x. Make sure that JAVA_HOME environment variable is properly set and that both java and javac are on your PATH.

Oracle:
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.

Postgres:
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 /etc/init.d/postgresql start in order to start the database. 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:

Switch to the "postgres" user account and edit "data/pg_hba.conf", adding the following line to the file:
host metacat metacat 127.0.0.1 255.255.255.255 password
If your host uses IPv6 addresses, you made need this line instead: host metacat metacat ::1 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff password
Edit the "data/postgres.conf" file and uncomment and edit the line starting with "tcpip_socket" so that it reads tcpip_socket = true
Run createdb metacat to create a new database
Run psql metacat to log in using the postgres account and create a new "metacat" user account
- In postgres, run CREATE USER metacat WITH UNENCRYPTED PASSWORD 'apasswordyoulike';
- This creates a new account called metacat on the database named metacat
- Note: there are many ways to do this, so others such as using ENCRYPTED passwords will work fine.
Exit the postgres account back to root and restart the postgres database with /etc/init.d/postgresql restart
Test logging into the postgres db using the metacat account with the following command: psql -U metacat -W -h localhost metacat

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. We note that the current build is not working with Ant 1.6.x, so you'll need to use an earler version. We have successfully used Ant 1.5.1, 1.5.2, and some earlier versions.

Install Tomcat into the directory of your choice. The directory in which you install Tomcat itself will be referred to as the "$CATALINA_HOME". We recommend that you install Tomcat version 5.0. More details about Tomcat installation is available here.

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. You'll need both the "metacat" module and the "utilities" module to be checked out in sibling directories. The command is as follows:

mkdir knb-software

cd knb-software

cvs checkout -P metacat

cvs checkout -P utilities

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

Edit `build.properties` File

Once you have either checked out or unzipped and untarred the source distribution, you can begin the installation process. Change into the metacat directory and edit the file called "build.properties". You will need to change a number of configuration properties to match the setup on your system.

The properties that you will likely need to change will include tomcat, tomcatversion, webapps, context, server, httpserver, database, jdbc-connect, jdbc-base, user, password, datafilepath, inlinedatafilepath, cvsroot, default-style, and administrators. Each is described in detail in the table below.

Properties you will likely need to change:

Property	Description	Default value and examples of other values
tomcat	The tomcat property is the location in which tomcat is installed.	Default: `/usr/local/devtools/jakarta-tomcat` Example: `C:/Tomcat5`
tomcatversion	The tomcatversion property is the version of your Tomcat. You should put tomcat3, tomcat4, or tomcat5 here.	Default: `tomcat5` Example: `tomcat5`
webapps	The webapps property is the location in which your tomcat servlet contexts are installed. This is typically "TOMCAT_HOME/webapps", where TOMCAT_HOME is the same value that you entered for the 'tomcat' property above.	Default: `/var/www/org.ecoinformatics.knb` Example: `C:/Tomcat5/webapps`
context	The context property 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.	Default: `knb` Example: `mycontext`
server	The server property is hostname of for the server on which Metacat is running (note that you should not include the 'http://' in the server property). The server setting should include the port number appended to the end if Tomcat is running stand-alone (see example).	Default: `knb.ecoinformatics.org` Example: `somehost.university.edu:8080`
httpserver	httpserver is the plain HTTP address on which Metacat is running (note that you should not include the 'http://' in the httpserver property). The httpserver setting should include the HTTP plain port number appended to the end if Tomcat is running stand-alone (see example).	Default: `knb.ecoinformatics.org` Example: `somehost.university.edu:8080`
ldapUrl	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.	Default: `ldap://ldap.ecoinformatics.org/dc=ecoinformatics,dc=org`
database	Select the database to use for metadata storage. Valid values are `oracle`, `postgresql`, or `sqlserver`. Note that sqlserver support is minimal and probably will not work without substantial changes on your part, possibly including code changes. We have not revcently tested on sqlserver.	Default: `oracle` Other possible values: `postgresql` `sqlserver`
jdbc-connect	The JDBC connection string used to connect to the database.	Default: `jdbc:oracle:thin:@metacat.nceas.ucsb.edu:1521:knb`
jdbc-base	The base directory for locating JDBC jar files (not needed for postgresql).	Default: `/usr/oracle/jdbc/lib` Example: `C:/jdev10g/jdbc/lib`
user	The database user name that you set up to use Metacat. For example, an Oracle username.	Default: `knb` Example: `metacatdb`
password	The database password that you set up to use Metacat.	Default: `yourPasswordHere` Example: `metacat123`
datafilepath	The datafilepath is the directory to store data files.	Default: `/var/metacat/data` Example: `C:/Tomcat5/data/knb/data`
inlinedatafilepath	The inlinedatafilepath is the directory to store inline data that has been extracted from EML documents.	Default: `/var/metacat/inline-data` Example: `C:/Tomcat5/data/knb/inlinedata`
default-style	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 one of the styles that ships with the default metacat distribution. Other possible settings are shown in the examples to the right.	Default: `knb` Examples: `default esa knb2 nceas nrs obfs specnet`
administrators	The administrators parameter lists the accounts that are allowed to perform administrative actions such as rebuilding indices for documents. The list can can contain more than one account separated by colons.	Default: `uid=jones,o=NCEAS,dc=ecoinformatics,dc=org` Examples: `uid=localadmin,o=ucnrs.org`
authority.context	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 TDWG site.	Default: authority
config.lsidauthority	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.	Default: ecoinformatics.org Examples: esa.org or sulphur.ecoinformatics.org

Note that the build file is preconfigured to install Metacat either using 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').

Other properties in build.properties that you can (but generally need not) change:

Property	Description	Default value and examples of other values
inst.cgi.dir	Installation directory for registry CGI scripts	Default: `/var/www/cgi-knb`
cgi-prefix		Default: `http://knb.ecoinformatics.org/cgi-bin`
knb-site-url	This is the URL to the web context root for the knb site. It is used for the qformat=knb skin only.	Default: `http://knb.ecoinformatics.org`
forcereplicationwaitingtime	The waiting time before replication is forced to begin after uploading a package. The default value should usually suffice.	Default: `30000`
cvsroot	CVS access to retrieve latest EML. Only used by developers in building the release.	Default: `:ext:${env.USER}@cvs.ecoinformatics.org:/cvs` Example: `:ext:myaccount@cvs.ecoinformatics.org:/cvs`

Metacat has a number of additional settable properties in file metacat/lib/metacat.properties. Under most circumstances, you will not need to modify this file because the properties of interest to you can be controlled by editing build.properties as described above. To learn more about Metacat's additional properties, see Metacat Properties File.

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.

Compilation and Installation

Ant allows compilation and installation to be done in one step. Change into the metacat directory and type:

ant install

or, if you are upgrading an existing installation, type:

ant clean upgrade

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.

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.

SQL Scripts

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.

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.

To run the scripts using ant, type ant installdb. This does not work for postgres, so you'll need to run the xmltables-postgres.sql script manually (see next paragraph).

To run the scripts manually, change to the metacat/build/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;

For postgres, use a command like: psql -U metacat -W -h localhost -f build/src/xmltables-postgres.sql metacat

Either way, 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. The script file name for PostgreSQL is xmltables-postgres.sql and for Microsoft SQL server is xmltables-sqlserver.sql.

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

describe xml_documents

and it should show:

    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)

Registering schemas and DTDs

Once the tables have been created, you should also register the Ecological Metadata Language (EML) DTDs and schemas. 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). If you are installing new, you can register the schema documents by running:

ant register-schemas

This command registers the EML DTDs' and schemas' location in the metacat server. Your database username and password have to be set correctly 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).

Upgrading SQL Scripts

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:

build/src/upgrade-db-to-1.2.sql
build/src/upgrade-db-to-1.3.sql
build/src/upgrade-db-to-1.4.sql
build/src/upgrade-db-to-1.5.sql

So, if you had an existing metacat 1.0 installation and you were upgrading to 1.5, you would need to run all four scripts in sequence: upgrade-db-to-1.2.sql, upgrade-db-to-1.3.sql, upgrade-db-to-1.4.sql, and upgrade-db-to-1.5.sql. However, if you were starting from a Metacat 1.4.x installation, you would only need to run the upgrade-db-to-1.5.sql script. Be sure to use the version of the scripts from the 'build' directory: they are customized for your installation in that directory.

Restart Tomcat

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, login as the user that runs your tomcat server (often "tomcat"), go to $CATALINA_HOME/bin and type:

   ./shutdown.sh 
   ./startup.sh

In the Tomcat startup messages you should see something in log file 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/yourcontext/

You should substitute your context name for "yourcontext" in the url above. If everything is working correctly, you should see a query page followed by an empty result set. Note that if you do not have Tomcat integrated with Apache you will probably have to type