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

Table of Contents
Introduction
Different Installation Options
Organization Of This Page
Quick Installation
Download Metacat Package
Create Metacat Directories
Install Java
Install Apache
Install Tomcat
Install PostgreSQL Database
Install Metacat War
Install LSID War
Configure Metacat
Quick Update
Download Metacat Package
Backup Existing Metacat Installation
Update Metacat War
Update LSID War
Configure Metacat
Pre-Installation
Minimum Requirements
Additional Required Software
Additional Software Setup
Java
Oracle
PostgreSQL
Ant
Apache
Tomcat
Download Metacat and Get War File
Download Metacat Binary and Get War File
Download Metacat Source Distribution
Download Metacat Source From SVN
Create War From Source
Installing Metacat
Create Metacat Directories
Install Metacat Binary (War)
Install Metacat From Source
Upgrading Existing Metacat
Stop the Running Metacat
Download Latest Metacat Application
Upgrade Metacat Binary (War)
Upgrade Metacat From Source
Restart Tomcat
Troubleshooting
Configure Metacat
Web Based Registry
Introduction
Different Installation Options

There are many different options to consider when installing Metacat. Some of these are:

The administrator will need to decide which combinations of these option are best suited to their system

Organization Of This Page

The first couple of sections on this page deal with quick command line instructions for installing and upgrading Metacat in the optimal environment, which is a binary distribution installation with Apache on Ubuntu Linux.

The remainder of the page deals with more detailed instructions including other installation options.

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
Create Metacat Directories
Install Java
Install Apache
Install Tomcat
Install PostgreSQL Database
Install Metacat War
Install LSID War
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
Backup Existing Metacat Installation
Update Metacat War
Update LSID War
Configure Metacat

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

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.

Additional 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

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.

PostgreSQL

PostgreSQL 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:

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.

Apache

If you are running Ubuntu/Debian, you can install the Apache web server by typing:

sudo apt-get install apache2
Otherwise, you can get Apache from the Apache Tomcat page.

Tomcat

Install Tomcat into the directory of your choice. The directory in which you install Tomcat itself will be referred to as the <tomcat_home>. We recommend that you install Tomcat version 5.5. If you are running Ubuntu/Debian, you can get Tomcat by typing:

sudo apt-get install tomcat5.5
Otherwise, you can get Tomcat from the Apache Tomcat page.

Download Metacat and Get War File

There are several ways to wind up with a Metacat war file, which is needed for installation. These are:

Since downloading the binary distribution is the easiest and most common install, it will be discussed here in detail. Links to source download/build instructions are also included in case you would like to go that route.

Download Metacat Binary and Get War File

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

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

for Windows systems, select the link that looks like:

metacat-bin-X.X.X.zip

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

Extract the Metacat package files on Linux systems by typing:

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

or, on Windows, use your system unzip utility to extract the zip file.

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.

Download Metacat Source Distribution

To get the Metacat source distribution, browse to the KNB Software Download Page. In the Metacat section, for Linux based systems, select the link that looks like:

metacat-src-X.X.X.tar.gz

for Windows systems, select the link that looks like:

metacat-src-X.X.X.zip

where X.X.X is the latest version of Metacat. Choose to save the file locally in the directory where your source should live.

Extract the Metacat package files on Linux systems by typing:

tar -xvzf metacat-src-X.X.X.tar.gz

or, on Windows, use your system unzip utility to extract the zip file.

Rename the metacat-X.X.X directory to metacat.

Note that you do not need to create the war file directly with a source installation since the Ant build file has an "install" target that will build and deploy the war for you. See the Installing Metacat for instructions.

Download Metacat Source From SVN

If you are checking out Metacat code from the SVN repository, you will need both Subversion (SVN) and CVS clients installed and configured on your system. Both are needed because, while Metacat has been migrated to SVN, some of its supporting libraries (eml, utilities and seek) have not yet been migrated. Eventually, SVN will be the only versioning client you will need. You will need to make sure you have the appropriate accounts on these systems. You won't have to worry about SVN or CVS if you are installing from a Metacat source distribution. These have all the required dependencies built in.

If you have not already installed Subversion and you are running Ubuntu/Debian, you can get it by typing:

sudo apt-get install subversion

Otherwise, you can get if from The Subversion homepage

If you have not already installed CVS and you are running Ubuntu/Debian, you can get it by typing:

sudo apt-get install cvs

Otherwise, you can get it from The Ximbiot CVS homepage

To check out the code from SVN, go to the directory where you would like the code to live and type:

svn co https://code.ecoinformatics.org/code/metacat/tags/METACAT_<rev> metacat

Where <rev> is the version of the code you want to check out (like 1_9).

If you are trying to check out the head, type:

svn co https://code.ecoinformatics.org/code/metacat/trunk metacat

You should see a list of files as they check out.

Note that you do not need to create the war file directly with a source installation since the Ant build file has an "install" target that will build and deploy the war for you. See the Installing Metacat for instructions.

Installing Metacat

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

Tomcat will look for it's application files (war files) in a configured directory. This is typically the <tomcat_home>/webapps directory, but your instance of Tomcat may be configured to look in a different directory. We will refer to your Tomcat application directory as <tomcat_app_dir>.

Create Metacat Directories

Metacat uses a base directory to store such things as store data and metadata, temporary files and configuration backups. This directory should be outside of the Tomcat application directory since the application directory gets wiped out during an upgrade. Create the metacat utility base directory by typing:

sudo mkdir

(Typically is '/var/metacat'.) Remember the directory you choose, since you will be asked to configure Metacat to point to it after startup.

Change the ownership of the directory by typing:

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 Metacat Binary (War)

Copy the war file to Tomcat:

sudo cp knb.war <tomcat_app_dir>
Install Metacat From Source

You will need Apache Ant to do the build. If you have not already installed Ant and you are running Ubuntu/Debian, you can get it by typing:

sudo apt-get install ant

Otherwise, you can get ant from The Apache Ant homepage

You should now have the Metacat source in a directory named "metacat" in your code directory (We will refer to the metacat source directory as <metacat_src_dir>.

To prepare for the build, edit the file at:

<metacat_src_dir>/build.properties

Make sure that the "build.tomcat.dir" property is set to your tomcat installation directory. For instance:

build.tomcat.dir=/usr/local/tomcat

Metacat will use some of the native Tomcat libraries during the build.

Make sure that the "app.deploy.dir" property is set to your application deployment directory. For instance:

app.deploy.dir=/usr/local/tomcat/webapps

If your cvs user is something other than the user your are logged in as, you will need to change the ${env.USER} part of the cvsroot property to be your cvs user. For instance:

cvsroot=:ext:cvs-user@cvs.ecoinformatics.org:/cvs

where your cvs user name is "cvs-user"

In the <metacat_src_dir>, run:

ant clean install

You will see the individual modules get built. You will be prompted for your cvs password several times. You should see a "BUILD SUCCESSFUL" message at the end.

You should see a new file named knb.war in your application deployment directory.

Configure Apache

You have the option of running Tomcat stand-alone or with with the Apache web server. Running with Apache is the more traditional setup since Apache is a more robust web server. There are some initial setup steps to get Apache talking to the Metacat application at the

the Metacat Apache Configuration page

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 <tomcat_home>/bin and type:

./shutdown.sh
Download Latest Metacat Application

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 several files:

The location where these files were extracted will be refered to as the the <metacat_package_dir> for the remainder of this documentation.

Upgrade Metacat Binary (War)

Tomcat will look for it's application files (war files) in a configured directory. This is typically the <tomcat_home>/webapps directory, but your instance of Tomcat may be configured to look in a different directory. We will refer to your Tomcat application directory as <tomcat_app_dir>.

If desired, back up your existing war file with a date:

sudo mv <tomcat_app_dir>/knb.war <tomcat_app_dir>/knb.war.<yyyymmdd>

Copy the war file to the Tomcat applications directory:

sudo cp knb.war <tomcat_app_dir>

Remove (or rename) the existing application directory:

sudo rm -rf <tomcat_home>/webapps/knb

or

sudo mv <tomcat_home>/webapps/knb <tomcat_home>/webapps/knb.<yyyymmdd>

Restart Tomcat:

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

Tomcat will expand your war file into a new application directory at startup time.

Upgrade Metacat From Source

The steps to upgrade Metacat from source are the same as installing from source. See the Install Metacat From Source section above.

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 <tomcat_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 has successfully loaded 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 the catalina.sh file in the 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.

Web Based Registry

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