r4571 - trunk/docs/user
daigle at ecoinformatics.org
daigle at ecoinformatics.org
Tue Nov 18 14:17:48 PST 2008
Author: daigle
Date: 2008-11-18 14:17:47 -0800 (Tue, 18 Nov 2008)
New Revision: 4571
Modified:
trunk/docs/user/metacatinstall.html
Log:
Updated existing installation instructions to be more inline with binary install instructions.
Modified: trunk/docs/user/metacatinstall.html
===================================================================
--- trunk/docs/user/metacatinstall.html 2008-11-18 22:16:48 UTC (rev 4570)
+++ trunk/docs/user/metacatinstall.html 2008-11-18 22:17:47 UTC (rev 4571)
@@ -62,9 +62,25 @@
<div class="toc2"><a href="#MinRequirements">Minimum Requirements</a></div>
<div class="toc2"><a href="#AdditionalRequiredSoftware">Additional Required Software</a></div>
<div class="toc1"><a href="#AdditionalSoftwareSetup">Additional Software Setup</a></div>
+ <div class="toc2"><a href="#AdditionalSoftwareJava">Java</a></div>
+ <div class="toc2"><a href="#AdditionalSoftwareOracle">Oracle</a></div>
+ <div class="toc2"><a href="#AdditionalSoftwarePostgres">PostgreSQL</a></div>
+ <div class="toc2"><a href="#AdditionalSoftwareAnt">Ant</a></div>
+ <div class="toc2"><a href="#AdditionalSoftwareTomcat">Tomcat</a></div>
<div class="toc1"><a href="#InstallingMetacat">Installing Metacat</a></div>
+ <div class="toc2"><a href="#InstallDownloadMetacat">Download Metacat Application</a></div>
+ <div class="toc2"><a href="#InstallMetacatWar">Install Metacat War</a></div>
+ <div class="toc2"><a href="#InstallRestartTomcat">Restart Tomcat</a></div>
+ <div class="toc2"><a href="#InstallTroubleshooting">Troubleshooting</a></div>
+ <div class="toc2"><a href="#InstallConfigureMetacat">Configure Metacat</a></div>
<div class="toc1"><a href="#UpgradingMetacat">Upgrading Existing Metacat</a></div>
- <div class="toc1"><a href="#Registry">Registry</a></div>
+ <div class="toc2"><a href="#UpgradeStopMetacat">Stop the Running Metacat</a></div>
+ <div class="toc2"><a href="#UpgradeDownloadMetacat">Download Latest Metacat Application</a></div>
+ <div class="toc2"><a href="#UpgradeMetacatWar">Upgrade Metacat War</a></div>
+ <div class="toc2"><a href="#UpgradeRestartTomcat">Restart Tomcat</a></div>
+ <div class="toc2"><a href="#UpgradeTroubleshooting">Troubleshooting</a></div>
+ <div class="toc2"><a href="#UpgradeConfigureMetacat">Configure Metacat</a></div>
+ <div class="toc1"><a href="#Registry">Web Based Registry</a></div>
</div>
<a name="QuickInstructions"></a><div class="header1">Quick Instructions</div>
@@ -117,6 +133,10 @@
<p>Set up and enable knb (Metacat) site configurations by typing:</p>
<div class="code">sudo cp <metacat_package_dir>/knb /etc/apache2/sites-available</div>
<div class="code">sudo a2ensite knb</div>
+ <p>If you are going to make use of an LSID server, set up and enable the authority service site
+ configurations by typing:</p>
+ <div class="code">sudo cp <metacat_package_dir>/authority /etc/apache2/sites-available</div>
+ <div class="code">sudo a2ensite authority</div>
<p>Restart apache to bring in changes by typing:</p>
<div class="code">sudo /etc/init.d/apache2 force-reload</div>
</div>
@@ -257,36 +277,37 @@
</ul>
</p>
-<table class="tabledefault" width="100%">
-<td class="tablehead" colspan="2"><p><a name="Additional Software Setup"><h2>Aditional Software Setup</h2></p></td>
-<tr>
-<td>
- <p class="header">Java</p>
+<a name="AdditionalSoftwareSetup"></a><div class="header1">Additional Software Setup</div>
+ <a name="AdditionalSoftwareJava"></a><div class="header2">Java</div>
<p>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 <a href="http://java.sun.com/j2se/1.5.0/">J2SE 5.0</a>
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.
</p>
- <p class="header">Oracle 8i or Postgres</p>
- <p><i>Oracle:</i><br>
- The Oracle RDBMS must be installed and running as a daemon on the system.
+ <a name="AdditionalSoftwareOracle"></a><div class="header2">Oracle 8i</div>
+ <p>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:
- <pre>lsnrctl start</pre>
- Your instance should have a table space of at least 5 MB (10 MB or higher
+ logging in as your Oracle user and typing the following:</p>
+
+ <div class="code">lsnrctl start</div>
+
+ <p>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.
- </p>
- <p><i>Postgres:</i><br>
- Postgres can be easily installed on most linux distributions and on
+ correctly set.</p>
+
+ <a name="AdditionalSoftwarePostgreSQL"></a><div class="header2">PostgreSQL</div>
+ <p>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
- <code>/etc/init.d/postgresql start</code> in order to start the database.
+ you can install the rpms for postgres and then run </p>
+
+ <div class="code">/etc/init.d/postgresql start</div>
+
+ <p>in order to start the database.
On Ubuntu and other Debian-based Linux distributions, you can use the apt-get command
to install postgres: <code>sudo apt-get install postgresql-8.0</code> and
then run <code>/etc/init.d/postgresql-8.0 start</code> to start.
@@ -319,7 +340,8 @@
<code>psql -U metacat -W -h localhost metacat</code></li>
</ul>
</p>
- <p class="header">Ant</p>
+
+ <a name="AdditionalSoftwareAnt"></a><div class="header2">Ant</div>
<p>
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
@@ -331,238 +353,153 @@
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. -->
</p>
- <p class="header">Tomcat</p>
+
+ <a name="AdditionalSoftwareTomcat"></a><div class="header2">Tomcat</div>
<p>
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 <a href=" http://jakarta.apache.org/tomcat/index.html">here</a>.
</p>
- </td>
-</tr>
-</table>
-<table class="tabledefault" width="100%">
-<td class="tablehead" colspan="2"><p><a name="Installing Metacat"><h2>Installing Metacat</h2></p></td>
-<tr>
-<td>
+<a name="InstallingMetacat"></a><div class="header1">Installing Metacat</div>
<a name="protocol"></a>
<p>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 - <a HREF="metacatinstall.html#Upgrade">Upgrading Existing Metacat</a>
+ this section and go to the next one - <a href="metacatinstall.html#Upgrade">Upgrading Existing Metacat</a>
- <h3>Download Metacat application</h3>
+ <a name="InstallDownloadMetacat"></a><div class="header2">Download Metacat Application</div>
+ <p>Browse to the
+ <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
+ In the Metacat section, select the link that looks like:</p>
+ <div class="code">metacat-bin-X.X.X.tar.gz</div>
+ <p>where X.X.X is the latest version of Metacat. Choose to save the file locally.</p>
+ <p>Extract the Metacat package files by typing:</p>
+ <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
+ <p>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.
+
+ <a name="InstallMetacatWar"></a><div class="header2">Install Metacat War</div>
+ <p>Copy the war file to Tomcat:</p>
+ <div class="code">sudo cp knb.war /usr/share/tomcat5.5/webapps</div>
+ <p>Restart Tomcat:</p>
+ <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
- <p>First <a href="/software/download.html">download metacat-1.9.0.tar.gz</a> from this site.</p><br>
+ <a name="InstallRestartTomcat"></a><div class="header2">Restart Tomcat</div>
+ <p>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: </p>
+
+ <div class="code">./shutdown.sh</div>
+ <div class="code">./startup.sh</div>
+
+ <p>In the Tomcat startup messages you should see something in the log file like:</p>
+
+ <div class="code">Metacat: [WARN]: Metacat (1.9.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]</div>
- <p>Extract the contents of the tar file in Linux/Mac by typing: </p>
- <pre>
- <b>
- tar-xvzf metacat-1.9.0.tar.gz
- </b>
- </pre>
-
- <h3>Copy war file to Tomcat application directory</h3>
+ <p>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:</p>
+
+ <div class="code">http://yourserver.yourdomain.com/yourcontext/</div>
+
+ <p>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:</p>
+
+ <div class="code">http://yourserver.yourdomain.com:8080/yourcontext/</div>
- <p>Copy knb.war to $CATALINA_HOME/webapps</p>
- <p>If desired, you can rename the war file to <yourcontext>.war</p>
-
- <h3>Create Metacat directory</h3>
+ <a name="InstallTroubleshooting"></a><div class="header2">Troubleshooting</div>
+ <p>If you see something like:</p>
- <p>Create the Metacat storage directory:</p>
- <pre>
- <b>
- mkdir /var/metacat
- </b>
- </pre>
+ <div class="code">java.lang.InternalError: Can't connect to X11 window server using 'yourservanme:0.0' as the value of the DISPLAY variable.</div>
- <p>Change the ownership of the Metacat storage directory to be the user that runs Tomcat:
- <pre>
- <b>
- chown tomcat:tomcat /var/metacat
- </b>
- </pre></p>
-
- <h3>Restart Tomcat</h3>
- <p>
- 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:
- <pre>
- <b>
- ./shutdown.sh
- ./startup.sh
- </b>
- </pre>
- In the Tomcat startup messages you should see something in the log file like:
- <pre>
- Metacat: [WARN]: Metacat (1.8.1) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]
- </pre>
- 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:
- <pre>
- http://yourserver.yourdomain.com/yourcontext/
- </pre>
- 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
- <pre>
- http://yourserver.yourdomain.com:8080/yourcontext/
- </pre>
- </p>
- <p><b>Troubleshooting</b>: 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.
- <p>You should add this line:
- <b>JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</b> at the first line of
- catalina.sh file in tomcat bin directory. The reason is that GeoServer uses X11 windows to draw graphics.
- </p>
+ <p>You should add this line: </p>
- <h3>Configure Metacat</h3>
- <p>
- Once you see the Metacat configuration screen, you can follow the instructions in the
- <a href="./metacatconfigure.html"> Configuring Metacat Section</a>
- to complete the internal configuration of Metacat.
- </p>
+ <div class="code">JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</div>
- <h3>Deploy wsdl file (Only for EarthGrid-enabled Metacat installation) </h3>
- <p>
- Once Tomcat is running successfully, there is another step for EarthGrid-enabled Metacat installation.
- In metacat directory, type:
- <pre><b>ant deploy-ecogrid</b></pre>
- It will generate wsdl files for EarthGrid services.
- </p>
+ <p>at the first line of the catalina.sh file in tomcat bin directory. The reason is that
+ GeoServer uses X11 windows to draw graphics.</p>
+
+ <a name="InstallConfigureMetacat"></a><div class="header2">Configure Metacat</div>
+ <p>Once you see the Metacat configuration screen, you can follow the instructions in the
+ <a href="./metacatconfigure.html"> Configuring Metacat Section</a>
+ to complete the internal configuration of Metacat.</p>
-</td>
-</tr>
-</table>
-
-<table class="tabledefault" width="100%">
-<td class="tablehead" colspan="2"><p><a name="Upgrade"><h2>Compilation and Upgrading Existing Metacat</h2></p></td>
-<tr>
-<td>
+<a name="UpgradingMetacat"></a><div class="header1">Upgrading Existing Metacat</div>
<a name="protocol"></a>
<p>The following instructions are for upgrading an existing Metacat.
- <p><h3>Stop the running Metacat</h3>
- <P>To do this, login as the user that runs your tomcat server (often "tomcat"),
- go to $CATALINA_HOME/bin and type:
- <pre><b>./shutdown.sh</b> </pre>
- <p>
- <h3>Run Ant Build</h3>
- <p>
- Ant allows compilation and upgrading to be done in one step.
- Change into the metacat directory and type:
- <pre><b>ant clean upgrade</b></pre>
- <p>
- 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.
- </p>
- <p>
- 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.
- </p>
-
- <p class="header">To install metacat LSID support, adjust the LSID-related
- properties in the build.properties files and type:
- <p class="header"><b>ant deploy-lsid</b>
+
+ <a name="UpgradeStopMetacat"></a><div class="header2">Stop the Running Metacat</div>
+ <p>To do this, login as the user that runs your tomcat server (often "tomcat"),
+ go to $CATALINA_HOME/bin and type:</p>
+
+ <div class="code">./shutdown.sh</div>
+
+ <a name="UpgradeDownloadMetacat"></a><div class="header2">Download Latest Metacat Application</div>
+ <p>Browse to the
+ <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
+ In the Metacat section, select the link that looks like:</p>
+ <div class="code">metacat-bin-X.X.X.tar.gz</div>
+ <p>where X.X.X is the latest version of Metacat. Choose to save the file locally.</p>
+ <p>Extract the Metacat package files by typing:</p>
+ <div class="code">tar -xvzf metacat-bin-X.X.X.tar.gz</div>
+ <p>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.</p>
- <p><h3>Upgrade SQL Scripts</h3></p>
- <P>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.</p>
- <p>
- 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:
- </p>
- <ul>
- <li>build/src/upgrade-db-to-1.2.sql</li>
- <li>build/src/upgrade-db-to-1.3.sql</li>
- <li>build/src/upgrade-db-to-1.4.sql</li>
- <li>build/src/upgrade-db-to-1.5.sql</li>
- <li>build/src/upgrade-db-to-1.6.sql</li>
- <li>build/src/upgrade-db-to-1.7.sql</li>
- <li>build/src/upgrade-db-to-1.8.sql</li>
- </ul>
- <p>
- 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.
- <em>Be sure to use the version of the scripts from the 'build/src' directory: they
- are customized for your installation in that directory.</em>
- </p>
- <p>
- Ant targets exist to do the upgrades, so you can also do the above described upgrade by running:<br />
- </p>
- <p>
- <strong>ant upgrade16</strong><br />
- <strong>ant upgrade17</strong><br />
- <strong>ant upgrade18</strong><br />
- </p>
+ <a name="UpgradeMetacatWar"></a><div class="header2">Upgrade Metacat War</div>
+ <p>Copy the war file to Tomcat:</p>
+ <div class="code">sudo cp knb.war /usr/share/tomcat5.5/webapps</div>
+ <p>Remove (or rename) the existing application directory:</p>
+ <div class="code">sudo rm -rf /usr/share/tomcat5.5/webapps/knb</div>
+ <p> or </p>
+ <div class="code">sudo mv /usr/share/tomcat5.5/webapps/knb /usr/share/tomcat5.5/webapps/knb.bak</div>
+ <p>Restart Tomcat:</p>
+ <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
+
+ <a name="UpgradeRestartTomcat"></a><div class="header2">Restart Tomcat</div>
+ <p>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: </p>
+
+ <div class="code">./startup.sh</div>
+
+ <p>In the Tomcat startup messages you should see something in the log file like:</p>
+
+ <div class="code">Metacat: [WARN]: Metacat (1.8.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]</div>
+
+ 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:</p>
+
+ <div class="code">http://yourserver.yourdomain.com/yourcontext/</div>
+
+ <p>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</p>
+
+ <div class="code">http://yourserver.yourdomain.com:8080/yourcontext/</div>
- </p>
- <h3>Restart Tomcat</h3>
- <p>
- 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:
- <pre>
- <b>
- ./startup.sh
- </b>
- </pre>
- In the Tomcat startup messages you should see something in the log file like:
- <pre>
- Metacat: [WARN]: Metacat (1.8.0) initialized. [edu.ucsb.nceas.metacat.MetaCatServlet]
- </pre>
- 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:
- <pre>http://yourserver.yourdomain.com/yourcontext/</pre>
- 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
- <pre>http://yourserver.yourdomain.com:8080/yourcontext/</pre>
- </p>
- <p><b>Troubleshooting</b>: 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.
- <p>You should add this line:
- <b>JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</b> at the first line of
- catalina.sh file in tomcat bin directory. The reason is that GeoServer uses X11 windows to draw graphics.
- </p>
+ <a name="UpgradeTroubleshooting"></a><div class="header2">Troubleshooting</div>
+ <p>If you see something like:
- <h3>Deploy wsdl file (Only for EarthGrid-enabled Metacat installation) </h3>
- <p>
- Once Tomcat is running successfully, there is another step for EarthGrid-enabled Metacat installation.
- In metacat directory, type:
- <pre><b>ant deploy-ecogrid</b></pre>
- It will generate wsdl files for EarthGrid services.
- </p>
+ <div class="code">java.lang.InternalError: Can't connect to X11 window server using 'yourservanme:0.0' as the value of the DISPLAY variable.</div>
+
+ <p>You should add this line: </p>
+
+ <div class="code">JAVA_OPTS="-Djava.awt.headless=true $JAVA_OPTS"</div>
+ <p>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.</p>
+
+ <a name="UpgradeConfigureMetacat"></a><div class="header2">Configure Metacat</div>
+ <p>Once you see the Metacat configuration screen, you can follow the instructions in the
+ <a href="./metacatconfigure.html"> Configuring Metacat Section</a>
+ to complete the internal configuration of Metacat.</p>
-</td>
-</tr>
-</table>
-
-<table class="tabledefault" width="100%">
-<td class="tablehead" colspan="2"><a name="Registry"><h2>Web-based Registry for Metacat</h2></td>
-<tr>
-<td>
-<p>The registry allows users to upload simple metadata documents directly from the web. See the separate
-<a href="registry_installation.html">Registry Installation Guide</a>.</p><br /><br />
-</td>
+<a name="Registry"></a><div class="header1">Web Based Registry</div>
+ <p>The registry allows users to upload simple metadata documents directly from the web. See the separate
+ <a href="registry_installation.html">Registry Installation Guide</a>.</p><br/><br/>
</body>
</html>
More information about the Metacat-cvs
mailing list