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.

Table of Contents
Quick Instructions
Quick Installation
Quick Update
Installing From Source Code
Windows XP
Ubuntu 8.04
Mac OS X
Pre-Installation
Minimum Requirements
Additional Required Software
Additional Software Setup
Installing Metacat
Upgrading Existing Metacat
Registry
Quick Instructions
Quick Installation

These are the installation instructions for a system that has Ubuntu 8.04 installed and has never had Metacat installed on it:

Download Metacat Package

Browse to the KNB Software Download Page. In the Metacat section, select the link that looks like:

metacat-bin-X.X.X.tar.gz

where X.X.X is the latest version of Metacat. Choose to save the file locally.

Extract the Metacat package files by typing:

tar -xvzf metacat-bin-X.X.X.tar.gz

You should see a war file and several supporting files. The location where these files were extracted will be refered to as the the <metacat_package_dir> for the remainder of this documentation.

Create Metacat Directories

Create the metacat utility base directory by typing:

sudo mkdir /var/metacat
sudo chown -R <tomcat_user> /var/metacat

where <tomcat_user> is the user that will start Tomcat. If you are starting Tomcat as the root user, you do not need to run the chown command.

Install Java

Install Java by typing:

sudo apt-get install sun-java5-jdk

hit "ok" then "yes" for license agreement

Install Apache

Install Apache and and Mod JK packages by typing:

sudo apt-get install apache2
sudo apt-get install libapache2-mod-jk

Setup Mod JK apache configuration by typing:

sudo cp <metacat_package_dir>/jk.conf /etc/apache2/mods-available
sudo cp <metacat_package_dir>/workers.properties /etc/apache2

Enable Apache Mod JK by typing:

sudo a2dismod jk
sudo a2enmod jk

Set up and enable knb (Metacat) site configurations by typing:

sudo cp <metacat_package_dir>/knb /etc/apache2/sites-available
sudo a2ensite knb

Restart apache to bring in changes by typing:

sudo /etc/init.d/apache2 force-reload
Install Tomcat

Install Tomcat 5.5 by typing:

sudo sudo apt-get install tomcat5.5

Install Metacat friendly Tomcat startup script by typing:

sudo /etc/init.d/tomcat5.5 stop
sudo mv /etc/init.d/tomcat5.5 /etc/init.d/tomcat5.5.bak
sudo cp <metacat_package_dir>/tomcat5.5 /etc/init.d/tomcat5.5
sudo chmod +x /etc/init.d/tomcat5.5

Install PostgreSQL Database

Install PostgreSQL by typing:

sudo apt-get install postgresql

Change to postgres user:

sudo su - postgres

Setup empty Metacat database instance editing the postgreSQL configuration file:

gedit /etc/postgresql/8.3/main/pg_hba.conf

and adding the following line:

host metacat metacat 127.0.0.1 255.255.255.255 password

Save the file, then create the metacat instance:

createdb metacat

Log into postgreSQL by typing:

psql metacat

and create the metacat user by typing at the psql prompt:

CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password';

where your_password is whatever password you would like for the metacat user.

Exit PostgreSQL by typing

\q

Restart the PostgreSQL database to bring in changes:

/etc/init.d/postgresql-8.3 restart

Log out of the postgres user account by typing:

logout

Test the installation and metacat account by typing:

psql -U metacat -W -h localhost metacat

Log back out of postgreSQL:

\q
Install Metacat War

Copy the war file to Tomcat:

sudo cp knb.war /usr/share/tomcat5.5/webapps

Restart Tomcat:

sudo /etc/init.d/tomcat5.5 restart
Configure Metacat

Refer to the documentation on Metacat Confguration to complete your installation of Metacat.

Quick Update

These are the instructions for a system that already has Metacat installed on it, but needs a Metacat upgrade:

Download Metacat Package

Browse to the KNB Software Download Page. In the Metacat section, select the link that looks like:

metacat-bin-X.X.X.tar.gz

where X.X.X is the latest version of Metacat. Choose to save the file locally.

Extract the Metacat package files by typing:

tar -xvzf metacat-bin-X.X.X.tar.gz

You should see a war file and several supporting files. The location where these files were extracted will be refered to as the the <metacat_package_dir> for the remainder of this documentation.

Backup Existing Metacat Installation

To be safe, it is best to backup the existing Metacat installation. Do so by typing:

cp /knb /knb.bak
cp /knb.war /knb.war.bak

Of course, you can use any backup strategy you like (or none at all).

Install Metacat War

Copy the war file to Tomcat:

sudo cp knb.war /usr/share/tomcat5.5/webapps

Restart Tomcat:

sudo /etc/init.d/tomcat5.5 restart
Configure Metacat

Refer to the documentation on Metacat Confguration to complete your installation of Metacat.

Installing From Source Code

These documents are meant to outline the metacat installation process on specific platforms. They are not a substitute for the below instructions and only meant as a supplemental guideline.

Windows XP

See the Windows XP installation instructions.

Ubuntu 8.04

See the Ubuntu 8.04 installation instructions.

Mac OS X

See the Mac OS X installation instructions.

Pre-Installation
Minimum Requirements

Installing Metacat requires a server running an SQL92 compliant database (Oracle 8i or Postgresql 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.

Aditional Software Setup

Java

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 J2SE 5.0 and this is the recommended version. Make sure that JAVA_HOME environment variable is properly set and that both java and javac are on your PATH.

Oracle 8i or Postgres

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. On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command to install postgres: sudo apt-get install postgresql-8.0 and then run /etc/init.d/postgresql-8.0 start to start. 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 may need this line instead: host metacat metacat ::1 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff password
  • If you are using Postgresql pre-8.0, you must 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

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. The latest metacat release was tested with Ant 1.6.5.

Tomcat

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.5. More details about Tomcat installation are available here.

Installing Metacat

This section is only for a fresh installation. If you are upgrading an existing Metacat, please skip this section and go to the next one - Upgrading Existing Metacat

Download Metacat application

First download metacat-1.9.0.tar.gz from this site.


Extract the contents of the tar file in Linux/Mac by typing: 

  
  tar-xvzf metacat-1.9.0.tar.gz

Copy war file to Tomcat application directory

Copy knb.war to $CATALINA_HOME/webapps

If desired, you can rename the war file to <yourcontext>.war

Create Metacat directory

Create the Metacat storage directory:

  
  mkdir /var/metacat

Change the ownership of the Metacat storage directory to be the user that runs Tomcat: 

  
  chown tomcat:tomcat /var/metacat

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 the log file like: 
	Metacat: [WARN]: Metacat (1.8.1) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]
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 Metacat configuration screen. Note that if you do not have Tomcat integrated with Apache you will probably have to type 
     http://yourserver.yourdomain.com:8080/yourcontext/

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

You should add this line: JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS" at the first line of catalina.sh file in tomcat bin directory. The reason is that GeoServer uses X11 windows to draw graphics.

Configure Metacat

Once you see the Metacat configuration screen, you can follow the instructions in the Configuring Metacat Section to complete the internal configuration of Metacat.

Deploy wsdl file (Only for EarthGrid-enabled Metacat installation)

Once Tomcat is running successfully, there is another step for EarthGrid-enabled Metacat installation. In metacat directory, type: 

ant deploy-ecogrid
It will generate wsdl files for EarthGrid services.

Compilation and Upgrading Existing Metacat

The following instructions are for upgrading an existing Metacat.

Stop the running Metacat

To do this, login as the user that runs your tomcat server (often "tomcat"), go to $CATALINA_HOME/bin and type: 

./shutdown.sh

Run Ant Build

Ant allows compilation and upgrading to be done in one step. Change into the metacat directory and 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 writable by user account under which Tomcat runs or you will not be able to upload data files to the system.

To install metacat LSID support, adjust the LSID-related properties in the build.properties files and type:

ant deploy-lsid

Upgrade SQL Scripts

Note: there is no SQL script that needs to be run when user upgrades the Metacat from 1.8.0 to 1.8.1 release.

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
  • build/src/upgrade-db-to-1.6.sql
  • build/src/upgrade-db-to-1.7.sql
  • build/src/upgrade-db-to-1.8.sql

For example, if you had an existing metacat 1.5 installation and you were upgrading to metacat 1.8, you would need to run three scripts in sequence: upgrade-db-to-1.6.sql, upgrade-db-to-1.7.sql, and upgrade-db-to-1.8.sql. However, if you were starting from a Metacat 1.7 installation, you would only need to run the upgrade-db-to-1.8.sql script. Be sure to use the version of the scripts from the 'build/src' directory: they are customized for your installation in that directory.

Ant targets exist to do the upgrades, so you can also do the above described upgrade by running:

ant upgrade16
ant upgrade17
ant upgrade18

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: 

   
   ./startup.sh
In the Tomcat startup messages you should see something in the log file like: 
	Metacat: [WARN]: Metacat (1.8.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]
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 
http://yourserver.yourdomain.com:8080/yourcontext/

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

You should add this line: JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS" at the first line of catalina.sh file in tomcat bin directory. The reason is that GeoServer uses X11 windows to draw graphics.

Deploy wsdl file (Only for EarthGrid-enabled Metacat installation)

Once Tomcat is running successfully, there is another step for EarthGrid-enabled Metacat installation. In metacat directory, type: 

ant deploy-ecogrid
It will generate wsdl files for EarthGrid services.

Web-based Registry for Metacat

The registry allows users to upload simple metadata documents directly from the web. See the separate Registry Installation Guide.