Metacat UNIX 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 |
|
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; 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 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 that you install Tomcat version 4.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 utilitiesOr you can download a gzipped tar file from this site. Edit
|
| 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:/Tomcat4 |
| tomcatversion | The tomcatversion property is the version of your Tomcat. You should put tomcat3, tomcat4, or tomcat5 here. We have most extensively tested Tomcat 4.x, but Tomcat 5.x seems to work fine as well. | Default:
tomcat4
Example: tomcat3
|
| 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:/Tomcat4/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:/Tomcat4/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:/Tomcat4/data/knb/inlinedata
|
| cvsroot | CVS access to retrieve latest EML. Only used by developers in building the release. | Default:
|
| cvsroot-alternate | CVS access to retrieve latest conversion styles. Only used by developers in building the release. | Default:
|
| 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: |
| 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
|
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 inbuild.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
|
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.
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_documentsand 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)
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:
So, if you had an existing metacat 1.0 installation and you were upgrading to 1.4, you would need to run all three scripts in sequence: upgrade-db-to-1.2.sql, upgrade-db-to-1.3.sql, and upgrade-db-to-1.4.sql. However, if you were starting from a Metacat 1.3.x installation, you would only need to run the upgrade-db-to-1.4.sql script.