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

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

• 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 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 by typing:
  sudo apt-get install sun-java5-jdk
• hit "ok" then "yes" for license agreement

• Install Apache and and Mod JK packages by typing:
  sudo apt-get install apache2 libapache2-mod-jk
• Set up 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
• If you want to run an LSID server along with the Metacat server, set up and enable the authority service site configurations by typing:
  sudo cp <metacat_package_dir>/authority /etc/apache2/sites-available
  sudo a2ensite authority
• Restart apache to bring in changes by typing:
  sudo /etc/init.d/apache2 force-reload

• 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 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

• Copy the war file to Tomcat:
  sudo cp <metacat_package_dir>/knb.war /usr/share/tomcat5.5/webapps
• Restart Tomcat:
  sudo /etc/init.d/tomcat5.5 restart

• If you want to run an LSID server along with the Metacat server, copy the authority.war file to Tomcat:
  sudo cp <metacat_package_dir>/authority.war /usr/share/tomcat5.5/webapps
• Restart Tomcat:
  sudo /etc/init.d/tomcat5.5 restart

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

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

• 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.

• To be safe, it is best to backup the existing Metacat installation. Do so by typing:
  cp <web_app_dir>/knb <web_app_dir>/knb.<yyyymmdd>
  cp <web_app_dir>/knb.war <web_app_dir>/knb.war.<yyyymmdd>
  Of course, you can use any backup strategy you like (or none at all).

• Copy the war file to Tomcat:
  sudo cp knb.war /usr/share/tomcat5.5/webapps
• Restart Tomcat:
  sudo /etc/init.d/tomcat5.5 restart

• If you want to run an LSID server along with the Metacat server, copy the authority.war file to Tomcat:
  sudo cp <metacat_package_dir>/authority.war /usr/share/tomcat5.5/webapps
• Restart Tomcat:
  sudo /etc/init.d/tomcat5.5 restart

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

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.

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.

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.

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:

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

in order to start the database. On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command to install postgres:

• Switch to the "postgres" user account
  sudo su - postgres
• 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
• Create metacat database by typing:
  createdb metacat
• Log in using the postgres account and create a new "metacat" user account by typing:
  psql metacat
  • 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 by typing:
  /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. The latest metacat release was tested with Ant 1.6.5.

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:

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

• Download Metacat binary distribution - which will have a pre-built war file.
• Download Metacat source distribution - which will then need to be built in order to create a war file.
• Download Metacat source from SVN - which will then need to be built in order to create a war file.

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.

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

for Windows systems, select the link that looks like:

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:

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.

If you would like to download the Metacat source distribution or checkout the source code from SVN, go to the Download and Build Metacat From Source page.

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

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:

(Typically is '/var/metacat'.) Remeber 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:

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.

Copy the war file to Tomcat:

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 following instructions are for upgrading an existing Metacat.

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

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

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

Extract the Metacat package files by typing:

You should see several files:

• knb.war - the Metacat application web archive file.
• knb - the web definition file used by Apache on ubuntu/debian Linux systems.
• jk.conf - the JkMount configuration file used by Apache on ubuntu/debian Linux systems.
• workers.properties - the workers definition file used by Apache on ubuntu/debian Linux systems.
• tomcat5.5 - the Tomcat startup script for Tomcat 5.5 installed with apt-get on ubuntu/debian Linux systems.
• authority - the optional LSID Server application web archive file.

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

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:

Copy the war file to the Tomcat applications directory:

Remove (or rename) the existing application directory:

or

Restart Tomcat:

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

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:

In the Tomcat startup messages you should see something in the log file like:

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

If you see something like:

You should add this line:

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.

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

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