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.
|
Aditional Software Setup |
Java You'll need a recent Java SDK, preferably j2sdk1.4.2 or later. 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 8i or Postgres Oracle: lsnrctl startYour 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:
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. 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. 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 to install Tomcat version 4.0. More details about tomcat installation is avaliable in 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 under the module name metacat. The command is as follows: cvs checkout -P metacatOr you can download a gzipped tar file from this site. Edit build.xml FileOnce 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.xml". You will need to change a number of configuration properties to match the setup on your system. If you are using oracle, you'll need to customize the properties in the "oracle" target. If you are using Postgres, you'll need to customize the properties in the "postgres" target. All users will need to customize the properties in the "config" target. The properties that you need to change will include jdbc-connect, dbDriver, dbAdapter, oracle_home, jdbc, tomcat, webapps, context, user, server, systemidserver, web-base-url, and default-style. Each is described in detail below. You should also verify that the jar file properties mentioned in the remainder of the config target are accessible at the paths listed -- the defaults will usually work. Note that the build file is preconfigured to install Metacat either using Oracle or PostgreSQL as a backend database. To change the database system, simply change the 'depends' attribute of the 'config' target to be the name of the database target that you wish to use (either 'oracle' or 'postgresql'). If you wish to use a different database system, add a new target for your database with the needed parameters and actions then add it to the 'depends' attribute. Properties you will likely need to change:
Note: DO NOT add a slash [/] to the end of these paths. Metacat will not function correctly if you do so. SQL ScriptsYou 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 To run the scripts manually, change to the metacat/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 xmltalbes_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_documentsand 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) Upgrading SQL ScriptsIf 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:
So, if you had an existing metacat 1.0 installation and you were upgrading to 1.3, you would need to run both upgrade-db-to-1.2.sql and upgrade-db-to-1.3.sql. Howver, if you were starting from a Metacat 1.2.x installation, you would only need to run the 1.3 upgrade script. |