<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>4. Downloading and Installing Metacat &mdash; Metacat 2.10.4 documentation</title>
    <link rel="stylesheet" href="_static/bootstrap.min.css" type="text/css" />
    <link rel="stylesheet" href="_static/font-awesome/css/font-awesome.min.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="_static/metacatui.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '2.10.4',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="Metacat 2.10.4 documentation" href="index.html" />
    <link rel="prev" title="3. License" href="license.html" />
    <link rel="next" title="5. Configuring Metacat" href="configuration.html" /> 
  </head>
  <body>
  <div id="metacatDocs">
	  <div class="banner">
	      <a href="index.html"><img class="logo" src="_static/metacat-logo-white.png" /></a>
	      <a href="index.html"><h1 class="title">Metacat: Metadata and Data Management Server</h1></a>
	      <img class="logo-right" src="_static/nceas-logo-white.png" />
	  </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right">
        <span id="searchbox" style="display: none;">
            <form class="search" action="search.html" method="get">
              <input type="text" name="q" size="18" />
              <input type="submit" value="Go" class="icon-search"/>
              <input type="hidden" name="check_keywords" value="yes" />
              <input type="hidden" name="area" value="default" />
            </form>
        </span>
        </li>
        <script type="text/javascript">$('#searchbox').show(0);</script>
        <li class="right">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a>
           </li>
        <li class="right">
          <a href="configuration.html" title="5. Configuring Metacat"
             accesskey="N">next</a>
           </li>
        <li class="right">
          <a href="license.html" title="3. License"
             accesskey="P">previous</a>
           </li>
        <li class="breadcrumb first"><a href="index.html">Metacat 2.10.4 documentation</a> &raquo;</li> 
      </ul>
      
    </div>

	
    <div class="document">
     	 <div class="documentwrapper">
	        <div class="bodywrapper">
	          <div class="body">
	            
  <div class="section" id="downloading-and-installing-metacat">
<h1><a class="toc-backref" href="#id9">4. Downloading and Installing Metacat</a><a class="headerlink" href="#downloading-and-installing-metacat" title="Permalink to this headline">¶</a></h1>
<p>Instructions for both Linux and Windows systems are included in this section.</p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#downloading-and-installing-metacat" id="id9">Downloading and Installing Metacat</a><ul>
<li><a class="reference internal" href="#system-requirements" id="id10">System Requirements</a></li>
<li><a class="reference internal" href="#installing-on-linux" id="id11">Installing on Linux</a><ul>
<li><a class="reference internal" href="#quick-start-overview" id="id12">Quick Start Overview</a></li>
<li><a class="reference internal" href="#downloading-metacat" id="id13">Downloading Metacat</a><ul>
<li><a class="reference internal" href="#download-the-metacat-installer-highly-recommended" id="id14">Download the Metacat Installer (Highly Recommended)</a></li>
<li><a class="reference internal" href="#download-metacat-source-code" id="id15">Download Metacat Source Code</a></li>
<li><a class="reference internal" href="#check-out-metacat-source-code-from-github-for-developers" id="id16">Check Out Metacat Source Code from GitHub (for Developers)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installing-and-configuring-required-software" id="id17">Installing and Configuring Required Software</a><ul>
<li><a class="reference internal" href="#id1" id="id18">Java 8</a></li>
<li><a class="reference internal" href="#id2" id="id19">Apache Tomcat</a></li>
<li><a class="reference internal" href="#apache-httpd-server-highly-recommended" id="id20">Apache HTTPD Server (Highly Recommended)</a></li>
<li><a class="reference internal" href="#postgresql-database" id="id21">PostgreSQL Database</a></li>
<li><a class="reference internal" href="#apache-ant-if-building-from-source" id="id22">Apache Ant (if building from Source)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installing-metacat" id="id23">Installing Metacat</a><ul>
<li><a class="reference internal" href="#new-install" id="id24">New Install</a></li>
<li><a class="reference internal" href="#upgrade-metacat" id="id25">Upgrade Metacat</a></li>
<li><a class="reference internal" href="#source-install-and-upgrade" id="id26">Source Install and Upgrade</a></li>
</ul>
</li>
<li><a class="reference internal" href="#optional-installation-options-lsid-server" id="id27">Optional Installation Options (LSID Server)</a><ul>
<li><a class="reference internal" href="#install-and-configure-the-lsid-server-shipped-with-metacat" id="id28">Install and configure the LSID Server shipped with Metacat</a></li>
<li><a class="reference internal" href="#to-install-the-lsid-server-from-a-source" id="id29">To install the LSID server from a source</a></li>
</ul>
</li>
<li><a class="reference internal" href="#troubleshooting" id="id30">Troubleshooting</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installing-on-windows" id="id31">Installing on Windows</a><ul>
<li><a class="reference internal" href="#download-metacat" id="id32">Download Metacat</a></li>
<li><a class="reference internal" href="#install-required-software" id="id33">Install Required Software</a><ul>
<li><a class="reference internal" href="#id3" id="id34">Java 8</a></li>
<li><a class="reference internal" href="#id4" id="id35">Apache Tomcat</a></li>
<li><a class="reference internal" href="#id5" id="id36">PostgreSQL Database</a></li>
</ul>
</li>
<li><a class="reference internal" href="#id6" id="id37">Installing Metacat</a><ul>
<li><a class="reference internal" href="#id7" id="id38">New Install</a></li>
<li><a class="reference internal" href="#upgrade" id="id39">Upgrade</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="system-requirements">
<h2><a class="toc-backref" href="#id10">4.1. System Requirements</a><a class="headerlink" href="#system-requirements" title="Permalink to this headline">¶</a></h2>
<p>In addition to meeting the recommended system requirements, the server on which
you wish to install Metacat must have the following software installed and
running correctly:</p>
<ul class="simple">
<li><a class="reference external" href="http://www.postgresql.org/">PostgreSQL</a></li>
<li><a class="reference external" href="http://ant.apache.org/">Apache Ant</a> (if building from source)</li>
<li><a class="reference external" href="http://tomcat.apache.org/">Apache Tomcat</a></li>
<li><a class="reference external" href="http://httpd.apache.org/">Apache HTTPD Server</a> (recommended)<ul>
<li>In order to use the Metacat Registry (and for a more robust Web-serving environment in general), the Apache Web server should be installed with Tomcat and the two should be integrated. See the installing Apache for more information.</li>
</ul>
</li>
<li><a class="reference external" href="http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html">Java 8</a> (Note: Java 7 is deprecated)</li>
</ul>
<p>System requirements for running Metacat:</p>
<ul class="simple">
<li>a server running <a class="reference external" href="http://www.postgresql.org/">PostgreSQL</a> database</li>
<li>at least 512MB RAM</li>
<li>200 MB disk space (Note: The amount of disk space required depends on the size of your RDBMS tablespace and the the size and number of documents stored. Metacat itself requires only about 140 MB of free space after installation).</li>
</ul>
</div>
<div class="section" id="installing-on-linux">
<h2><a class="toc-backref" href="#id11">4.2. Installing on Linux</a><a class="headerlink" href="#installing-on-linux" title="Permalink to this headline">¶</a></h2>
<p>This section contains instructions for downloading and installing Metacat on
Linux systems. As Mac OS X is based on BSD Unix, these Linux instructions can
be adapted to also work on Mac OS X (although the exact commands for
downloading and installing packages will differ due to the different package
management approaches on the Mac).</p>
<div class="section" id="quick-start-overview">
<h3><a class="toc-backref" href="#id12">4.2.1. Quick Start Overview</a><a class="headerlink" href="#quick-start-overview" title="Permalink to this headline">¶</a></h3>
<p>For the impatient or those who have already installed Metacat and know what
they are doing, here are the steps needed to install Metacat. Detailed
instructions for each step are in the next section.</p>
<ol class="arabic simple">
<li>Download and install prerequisites (<a class="reference external" href="http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html">Java 8</a>, <a class="reference external" href="http://tomcat.apache.org/">Apache Tomcat</a> 7, <a class="reference external" href="http://www.postgresql.org/">PostgreSQL</a>, <a class="reference external" href="http://httpd.apache.org/">Apache HTTPD Server</a>)</li>
<li>Create a database in PostgreSQL named &#8216;metacat&#8217; and authorize access to it in <code class="docutils literal"><span class="pre">pb_hba.conf</span></code> for the user &#8216;metacat&#8217;</li>
<li>Log in to PostgreSQL and create the &#8216;metacat&#8217; user</li>
<li>Download Metacat from the <a class="reference external" href="http://knb.ecoinformatics.org/software/metacat/">Metacat Download Page</a> and extract the archive</li>
<li><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">mkdir</span> <span class="pre">/var/metacat;</span> <span class="pre">sudo</span> <span class="pre">chown</span> <span class="pre">-R</span> <span class="pre">&lt;tomcat_user&gt;</span> <span class="pre">/var/metacat</span></code></li>
<li><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">cp</span> <span class="pre">&lt;metacat_package_dir&gt;/metacat.war</span> <span class="pre">&lt;tomcat_app_dir&gt;</span></code></li>
<li><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">cp</span> <span class="pre">&lt;metacat_package_dir&gt;/metacat-index.war</span> <span class="pre">&lt;tomcat_app_dir&gt;</span></code></li>
<li><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">cp</span> <span class="pre">&lt;metacat_package_dir&gt;/metacatui.war</span> <span class="pre">&lt;tomcat_app_dir&gt;</span></code></li>
<li><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">/etc/init.d/tomcat7</span> <span class="pre">restart</span></code></li>
<li>Configure Metacat through the Web interface</li>
</ol>
</div>
<div class="section" id="downloading-metacat">
<h3><a class="toc-backref" href="#id13">4.2.2. Downloading Metacat</a><a class="headerlink" href="#downloading-metacat" title="Permalink to this headline">¶</a></h3>
<p>Before installing Metacat, please ensure that all required software is
installed and running correctly. To obtain a Metacat WAR file, which is needed
for installation, download one of the following:</p>
<ul class="simple">
<li>the Metacat installer, which has a pre-built WAR file,</li>
<li>the Metacat source distribution, which must be built in order to create a WAR file,</li>
<li>the Metacat source code from SVN. You must build the source code in order to create a WAR file.</li>
</ul>
<p>Instructions for all three options are discussed below. Note that downloading
the installer (described in the next section) is the simplest way to get
started.</p>
<div class="section" id="download-the-metacat-installer-highly-recommended">
<h4><a class="toc-backref" href="#id14">4.2.2.1. Download the Metacat Installer (Highly Recommended)</a><a class="headerlink" href="#download-the-metacat-installer-highly-recommended" title="Permalink to this headline">¶</a></h4>
<p>Downloading the Metacat Installer is the simplest way to get started with the
application. To download the installer:</p>
<ol class="arabic simple">
<li>Browse to the <a class="reference external" href="http://knb.ecoinformatics.org/software/metacat/">Metacat Download Page</a>. In the Metacat section, select the link to the &#8220;GZIP file&#8221; (the link should look like: metacat-bin-X.X.X.tar.gz, where X.X.X is the latest version of Metacat e.g., 2.10.4)</li>
<li>Save the file locally.</li>
<li>Extract the Metacat package files by typing:</li>
</ol>
<div class="highlight-python"><div class="highlight"><pre>tar -xvzf metacat-bin-X.X.X.tar.gz
</pre></div>
</div>
<p>You should see a WAR file and several sample supporting files (Table 2.1). The
extraction location will be referred to as the <code class="docutils literal"><span class="pre">&lt;metacat_package_dir&gt;</span></code> for the
remainder of this documentation.</p>
<table border="1" class="docutils">
<colgroup>
<col width="14%" />
<col width="86%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">File</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>metacat.war</td>
<td>The Metacat Web archive file (WAR)</td>
</tr>
<tr class="row-odd"><td>metacat-site.conf</td>
<td>Sample Web definition file used by Apache on Ubuntu/Debian Linux systems.</td>
</tr>
<tr class="row-even"><td>metacat-site-ssl.conf</td>
<td>Sample SSL definition file used by Apache on Ubuntu/Debian Linux systems.</td>
</tr>
<tr class="row-odd"><td>jk.conf</td>
<td>Sample JkMount configuration file used by Apache on Ubuntu/Debian Linux systems.</td>
</tr>
<tr class="row-even"><td>workers.properties</td>
<td>Sample workers definition file used by Apache on Ubuntu/Debian Linux systems.</td>
</tr>
<tr class="row-odd"><td>metacat-index.war</td>
<td>The Metacat Index WAR for supporting SOLR query features Optional unless Metacat UI is being used.</td>
</tr>
<tr class="row-even"><td>metacatui.war</td>
<td>The Metacat UI - can be deployed as a webapp or directly in webserverMetacat UI requires metacat-index be deployed and configured.</td>
</tr>
<tr class="row-odd"><td>authority.war</td>
<td>The optional LSID Server application WAR</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="download-metacat-source-code">
<h4><a class="toc-backref" href="#id15">4.2.2.2. Download Metacat Source Code</a><a class="headerlink" href="#download-metacat-source-code" title="Permalink to this headline">¶</a></h4>
<p>To get the Metacat source distribution:</p>
<ol class="arabic simple">
<li>Browse to the <a class="reference external" href="http://knb.ecoinformatics.org/software/metacat/">Metacat Download Page</a>. In the Metacat section, select the link to the Metacat Source code (it will look something like this: metacat-src-X.X.X.tar.gz, where X.X.X is the latest version of Metacat, e.g., 2.10.4).</li>
<li>Save the file locally.</li>
<li>Extract the Metacat package files by typing (replace X.X.X with the current version number):</li>
</ol>
<div class="highlight-python"><div class="highlight"><pre>tar -xvzf metacat-src-X.X.X.tar.gz
</pre></div>
</div>
<ol class="arabic simple" start="4">
<li>Rename the metacat-X.X.X directory to metacat.</li>
</ol>
<p>Note that you do not need to create the WAR file directly because the Ant
build-file has an &#8220;install&#8221; target that will build and deploy the WAR for you.</p>
</div>
<div class="section" id="check-out-metacat-source-code-from-github-for-developers">
<h4><a class="toc-backref" href="#id16">4.2.2.3. Check Out Metacat Source Code from GitHub (for Developers)</a><a class="headerlink" href="#check-out-metacat-source-code-from-github-for-developers" title="Permalink to this headline">¶</a></h4>
<div class="sidebar">
<p class="first sidebar-title">Installing an Git Client:</p>
<p>If you have not already installed Git and you are running Ubuntu/Debian,
you can get the Git client by typing:</p>
<div class="last highlight-python"><div class="highlight"><pre>sudo apt-get install git
</pre></div>
</div>
</div>
<p>To clone the repository from GitHub, go to the directory where you would like the
code to live and type:</p>
<div class="highlight-python"><div class="highlight"><pre>git clone https://github.com/nceas/metacat metacat
</pre></div>
</div>
<p>The entire Metacat repository will be cloned to your local machine and the current branch is the master branch which is constantly maintained in a state ready for release. Detailed information about the code contribution please see:</p>
<p><a class="reference external" href="https://github.com/NCEAS/metacat/blob/master/CONTRIBUTING.md">https://github.com/NCEAS/metacat/blob/master/CONTRIBUTING.md</a></p>
<p>Note that you do not need to create the WAR file directly because the Ant
build-file has an &#8220;install&#8221; target that will build and deploy the WAR for you.</p>
</div>
</div>
<div class="section" id="installing-and-configuring-required-software">
<h3><a class="toc-backref" href="#id17">4.2.3. Installing and Configuring Required Software</a><a class="headerlink" href="#installing-and-configuring-required-software" title="Permalink to this headline">¶</a></h3>
<p>Before you can install and run Metacat, you must ensure that a recent Java SDK,
PostgreSQL, Ant (if
installing from source), and Tomcat are installed and running correctly. We
also highly recommend that you install Apache Web server, as it provides a more
robust Web-serving environment and is required by some Metacat functionality.</p>
<ul class="simple">
<li><a class="reference external" href="http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html">Java 8</a></li>
<li><a class="reference external" href="http://tomcat.apache.org/">Apache Tomcat</a></li>
<li><a class="reference external" href="http://httpd.apache.org/">Apache HTTPD Server</a> (Highly Recommended)</li>
<li><a class="reference external" href="http://www.postgresql.org/">PostgreSQL</a> Database</li>
<li><a class="reference external" href="http://ant.apache.org/">Apache Ant</a> (if building from Source)</li>
</ul>
<div class="section" id="id1">
<h4><a class="toc-backref" href="#id18">4.2.3.1. Java 8</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
<p>To run Metacat, you should use Java 8. Make sure that the JAVA_HOME
environment variable is properly set and that both <code class="docutils literal"><span class="pre">java</span></code> and <code class="docutils literal"><span class="pre">javac</span></code>
are on your PATH.</p>
<p>To install Java if you are running <a class="reference external" href="http://www.ubuntu.com/">Ubuntu</a>/Debian, you can install using apt-get:</p>
<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install openjdk-8-jdk
</pre></div>
</div>
<p>If you are not using <a class="reference external" href="http://www.ubuntu.com/">Ubuntu</a>/Debian, you can get Java from the <a class="reference external" href="http://www.oracle.com/">Oracle</a> website and install using the RPM or other installer (Windows).</p>
</div>
<div class="section" id="id2">
<h4><a class="toc-backref" href="#id19">4.2.3.2. Apache Tomcat</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
<p>We recommend that you install Tomcat 6 or 7 or 8 into the directory of your choice. The newer versions are preferred.
Included with the Metacat download is a Tomcat-friendly start-up script that
should be installed as well.</p>
<p>Note: we will refer to the Tomcat installation directory as <code class="docutils literal"><span class="pre">&lt;tomcat_home&gt;</span></code> for
the remainder of the documentation.</p>
<p>If you are running <a class="reference external" href="http://www.ubuntu.com/">Ubuntu</a>/Debian, get Tomcat by typing:</p>
<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install tomcat7
</pre></div>
</div>
<p>Otherwise, get Tomcat from the <a class="reference external" href="http://tomcat.apache.org/">Apache Tomcat</a> page.</p>
<p>After installing Tomcat, you can switch back to the Sun JDK by typing:</p>
<div class="highlight-python"><div class="highlight"><pre>sudo update-alternatives --config java
</pre></div>
</div>
<p>and selecting the correct Java installation.</p>
<p>If using Tomcat with Apache/mod_jk, enable the AJP connector on port 8009 by uncommenting that section in:</p>
<div class="highlight-python"><div class="highlight"><pre>&lt;tomcat_home&gt;/conf/server.xml
</pre></div>
</div>
<p>For DataONE deployments edit:</p>
<div class="highlight-python"><div class="highlight"><pre>/etc/tomcat7/catalina.properties
</pre></div>
</div>
<p>to include:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">tomcat</span><span class="o">.</span><span class="n">util</span><span class="o">.</span><span class="n">buf</span><span class="o">.</span><span class="n">UDecoder</span><span class="o">.</span><span class="n">ALLOW_ENCODED_SLASH</span><span class="o">=</span><span class="n">true</span>
<span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">catalina</span><span class="o">.</span><span class="n">connector</span><span class="o">.</span><span class="n">CoyoteAdapter</span><span class="o">.</span><span class="n">ALLOW_BACKSLASH</span><span class="o">=</span><span class="n">true</span>
</pre></div>
</div>
</div>
<div class="section" id="apache-httpd-server-highly-recommended">
<h4><a class="toc-backref" href="#id20">4.2.3.3. Apache HTTPD Server (Highly Recommended)</a><a class="headerlink" href="#apache-httpd-server-highly-recommended" title="Permalink to this headline">¶</a></h4>
<p>Although you have the option of running Metacat with only the Tomcat server, we
highly recommend that you run it behind the Apache Web server for several
reasons; running Tomcat with the Apache server provides a more robust Web
serving environment. The Apache Web server is required if you wish to
install and run the Metacat Registry or to use the Metacat Replication feature.</p>
<div class="sidebar">
<p class="first sidebar-title">Configuring Apache on an OS other than Ubuntu/Debian</p>
<p>If you are running on an O/S other than Ubuntu/Debian (e.g., Fedora Core or
RedHat Linux) or if you installed the Apache source or binary, you must
manually edit the Apache configuration file, where &lt;apache_install_dir&gt; is the
directory in which Apache is installed:</p>
<div class="highlight-python"><div class="highlight"><pre>&lt;apache_install_dir&gt;/conf/httpd.conf
</pre></div>
</div>
<ol class="arabic simple">
<li>Configure the log location and level for Mod JK. If your configuration file does not already have the following section, add it and set the log location to any place you&#8217;d like:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>&lt;IfModule mod_jk.c&gt;
  JkLogFile &quot;/var/log/tomcat/mod_jk.log&quot;
  JkLogLevel info
&lt;/IfModule&gt;
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="2">
<li>Configure apache to route traffic to the Metacat application. ServerName should be set to the DNS name of the Metacat server. ScriptAlias and the following Directory section should both point to the cgi-bin directory inside your Metacat installation:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>&lt;VirtualHost XXX.XXX.XXX.XXX:80&gt;
  DocumentRoot /var/www
  ServerName dev.nceas.ucsb.edu
  ## Allow CORS requests from all origins to use cookies
  #SetEnvIf Origin &quot;^(.*)$&quot; ORIGIN_DOMAIN=$1
  #Header set Access-Control-Allow-Origin &quot;%{ORIGIN_DOMAIN}e&quot; env=ORIGIN_DOMAIN
  Header set Access-Control-Allow-Headers &quot;Authorization, Content-Type, Origin, Cache-Control&quot;
  Header set Access-Control-Allow-Methods &quot;GET, POST, PUT, OPTIONS&quot;
  Header set Access-Control-Allow-Credentials &quot;true&quot;
  ErrorLog /var/log/httpd/error_log
  CustomLog /var/log/httpd/access_log common
  ScriptAlias /cgi-bin/ &quot;/var/www/cgi-bin/&quot;
  &lt;Directory /var/www/cgi-bin/&gt;
    AllowOverride None
    Options ExecCGI
    Order allow,deny
    Allow from all
  &lt;/Directory&gt;
  ScriptAlias /metacat/cgi-bin/ &quot;/var/www/webapps/metacat/cgi-bin/&quot;
  &lt;Directory &quot;/var/www/webapps/metacat/cgi-bin/&quot;&gt;
    AllowOverride None
    Options ExecCGI
    Order allow,deny
    Allow from all
  &lt;/Directory&gt;
  JkMount /metacat ajp13
  JkMount /metacat/* ajp13
  JkMount /metacat/metacat ajp13
  JkUnMount /metacat/cgi-bin/* ajp13
  JkMount /metacatui ajp13
  JkMount /metacatui/* ajp13
  JkMount /*.jsp ajp13
&lt;/VirtualHost&gt;
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="3">
<li>Copy the &#8220;workers.properties&#8221; file provided by Metacat into your Apache configuration directory (&lt;apache_install_dir&gt;/conf/).  Depending on whether you are installing from binary distribution or source, the workers.properties file will be in one of two locations:</li>
</ol>
<blockquote>
<div><ul class="simple">
<li>the directory in which you extracted the Metacat distribution (for binary distribution)</li>
<li>&lt;metacat_code_dir&gt;/src/scripts/workers.properties (for both the source distribution and source code checked out from SVN)</li>
</ul>
</div></blockquote>
<ol class="arabic simple" start="4">
<li>Edit the workers.properties file and make sure the following properties are set correctly:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>workers.tomcat_home -  set to the Tomcat install directory.
workers.java_home - set to the Java install directory.
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="5">
<li>Enable the Apache Mod HEADERS:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo a2enmod headers
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="6">
<li>Restart Apache to bring in changes by typing:</li>
</ol>
<blockquote class="last">
<div><div class="highlight-python"><div class="highlight"><pre>sudo /etc/init.d/apache2 restart
</pre></div>
</div>
</div></blockquote>
</div>
<p>This section contains instructions for installing and configuring the Apache
Web server for Metacat on an <a class="reference external" href="http://www.ubuntu.com/">Ubuntu</a>/Debian system. Instructions for configuring
Apache running on other Linux systems are included in the sidebar.</p>
<ol class="arabic simple">
<li>Install the Apache and Mod JK packages (Mod JK is the module Apache uses to talk to Tomcat applications) by typing:</li>
</ol>
<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install apache2 libapache2-mod-jk
</pre></div>
</div>
<p>If you are installing the Apache server on an Ubuntu/Debian system, and you
installed Apache using apt-get as described above, the Metacat code will have
helper files that can be dropped into directories to configure Apache.
Depending on whether you are installing from binary distribution or source,
these helper files will be in one of two locations:</p>
<ul class="simple">
<li>the directory in which you extracted the distribution (for binary distribution)</li>
<li><code class="docutils literal"><span class="pre">&lt;metacat_code_dir&gt;/src/scripts</span></code> (for both the source distribution and source code checked out from SVN).  We will refer to the directory with the helper scripts as <code class="docutils literal"><span class="pre">&lt;metacat_helper_dir&gt;</span></code> and the directory where Apache is installed (e.g., <code class="docutils literal"><span class="pre">/etc/apache2/</span></code>) as <code class="docutils literal"><span class="pre">&lt;apache_install_dir&gt;</span></code>.</li>
</ul>
<ol class="arabic simple" start="2">
<li>Set up Mod JK apache configuration by typing:</li>
</ol>
<div class="highlight-python"><div class="highlight"><pre>sudo cp &lt;metacat_helper_dir&gt;/debian/jk.conf &lt;apache_install_dir&gt;/mods-available
sudo cp &lt;metacat_helper_dir&gt;/debian/workers.properties &lt;apache_install_dir&gt;
</pre></div>
</div>
<ol class="arabic simple" start="3">
<li>Disable and re-enable the Apache Mod JK module to pick up the new changes:</li>
</ol>
<div class="highlight-python"><div class="highlight"><pre>sudo a2dismod jk
sudo a2enmod jk
</pre></div>
</div>
<ol class="arabic simple" start="4">
<li>Apache needs to know about the Metacat site. The helper file named &#8220;metacat-site.conf&#8221; has rules that tell Apache which traffic to route to Metacat. Set up Metacat site by dropping the metacat-site file into the sites-available directory and running a2ensite to enable the site:</li>
</ol>
<div class="highlight-python"><div class="highlight"><pre>sudo cp &lt;metacat_helper_dir&gt;/metacat-site.conf &lt;apache_install_dir&gt;/sites-available
sudo a2ensite metacat-site.conf
</pre></div>
</div>
<ol class="arabic simple" start="5">
<li>Disable the default Apache site configuration:</li>
</ol>
<div class="highlight-python"><div class="highlight"><pre>sudo a2dissite 000-default
</pre></div>
</div>
<ol class="arabic simple" start="6">
<li>Restart Apache to bring in changes by typing:</li>
</ol>
<div class="highlight-python"><div class="highlight"><pre>sudo /etc/init.d/apache2 restart
</pre></div>
</div>
</div>
<div class="section" id="postgresql-database">
<h4><a class="toc-backref" href="#id21">4.2.3.4. PostgreSQL Database</a><a class="headerlink" href="#postgresql-database" title="Permalink to this headline">¶</a></h4>
<p>Currently Metacat only supports <a class="reference external" href="http://www.postgresql.org/">PostgreSQL</a>. You can choose the release versions of PostgreSQL 8, 9, 10 or 11. The newer versions are preferred. To install and configure <a class="reference external" href="http://www.postgresql.org/">PostgreSQL</a>:</p>
<ol class="arabic simple">
<li>If you are running <a class="reference external" href="http://www.ubuntu.com/">Ubuntu</a>/Debian, get PostgreSQL by typing:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo apt-get install postgresql
</pre></div>
</div>
<p>On other systems, install the rpms for postgres.</p>
</div></blockquote>
<ol class="arabic simple" start="2">
<li>Start the database by running:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo /etc/init.d/postgresql-8.4 start
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="3">
<li>Change to postgres user:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo su - postgres
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="4">
<li>Set up an empty Metacat database instance by editing the postgreSQL configuration file:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre><span class="n">gedit</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">postgresql</span><span class="o">/</span><span class="mf">8.4</span><span class="o">/</span><span class="n">main</span><span class="o">/</span><span class="n">pg_hba</span><span class="o">.</span><span class="n">conf</span>
</pre></div>
</div>
<p>Add the following line to the configuration file:</p>
<div class="highlight-python"><div class="highlight"><pre>host metacat metacat 127.0.0.1 255.255.255.255 password
</pre></div>
</div>
<p>Save the file and then create the Metacat instance:</p>
<div class="highlight-python"><div class="highlight"><pre>createdb metacat
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="5">
<li>Log in to postgreSQL by typing:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>psql metacat
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="6">
<li>At the psql prompt, create the Metacat user by typing:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>CREATE USER metacat WITH PASSWORD &#39;your_password&#39;;
</pre></div>
</div>
<p>where &#8216;your_password&#8217; is whatever password you would like for the Metacat user.</p>
</div></blockquote>
<ol class="arabic simple" start="7">
<li>Exit PostgreSQL by typing</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>\q
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="8">
<li>Restart the PostgreSQL database to bring in changes:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>/etc/init.d/postgresql-8.4 restart
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="9">
<li>Log out of the postgres user account by typing:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre><span class="n">logout</span>
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="10">
<li>Test the installation and Metacat account by typing:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>psql -U metacat -W -h localhost metacat
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="11">
<li>Log out of postgreSQL:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>\q
</pre></div>
</div>
</div></blockquote>
<p>The Metacat servlet automatically creates the required database schema. For
more information about configuring the database, please see Database
Configuration.</p>
</div>
<div class="section" id="apache-ant-if-building-from-source">
<h4><a class="toc-backref" href="#id22">4.2.3.5. Apache Ant (if building from Source)</a><a class="headerlink" href="#apache-ant-if-building-from-source" title="Permalink to this headline">¶</a></h4>
<p>If you are building Metacat from a source distribution or from source code
checked out from SVN, Ant is required. (Users installing Metacat from the
binary distribution do not require it.) Ant is a Java-based build application
similar to Make on UNIX systems. It takes build instructions from a file named
&#8220;build.xml&#8221;, which is found in the root installation directory. Metacat source
code comes with a default &#8220;build.xml&#8221; file that may require some modification
upon installation.</p>
<p>If you are running Ubuntu/Debian, get Ant by typing:</p>
<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install ant
</pre></div>
</div>
<p>Otherwise, get Ant from the <a class="reference external" href="http://ant.apache.org/">Apache Ant</a> homepage.</p>
<p>Ant should be installed on your system and the &#8220;ant&#8221; executable shell script
should be available in the user&#8217;s path. The latest Metacat release was tested
with Ant 1.8.2.</p>
</div>
</div>
<div class="section" id="installing-metacat">
<h3><a class="toc-backref" href="#id23">4.2.4. Installing Metacat</a><a class="headerlink" href="#installing-metacat" title="Permalink to this headline">¶</a></h3>
<p>Instructions for a new install, an upgrade, and a source install are included
below.</p>
<div class="section" id="new-install">
<h4><a class="toc-backref" href="#id24">4.2.4.1. New Install</a><a class="headerlink" href="#new-install" title="Permalink to this headline">¶</a></h4>
<p>Before installing Metacat, please ensure that all required applications are
installed, configured to run with Metacat, and running correctly. If you are
upgrading an existing Metacat servlet, please skip to Upgrade. For information
about installing from source, skip to Source Install and Upgrade.</p>
<p>To install a new Metacat servlet:</p>
<ol class="arabic simple">
<li>Create the Metacat directory. Metacat uses a base directory to store data, metadata, temporary files, and configuration backups. This directory should be outside of the Tomcat application directory so that it will not get wiped out during an upgrade. Typically, the directory is &#8216;/var/metacat&#8217;, as shown in the instructions. If you choose a different location, remember it. You will be asked to configure Metacat to point to the base directory at startup.  Create the Metacat directory by typing:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo mkdir /var/metacat
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="2">
<li>Change the ownership of the directory to the user that will start Tomcat by typing (note: If you are starting Tomcat as the root user, you do not need to run the chown command):</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo chown -R &lt;tomcat_user&gt; /var/metacat
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="3">
<li>Install the Metacat, Metacat-index and MetacatUI WAR in the Tomcat web-application directory. For instructions on downloading the Metacat WAR, please see Downloading Metacat.  Typically, Tomcat will look for its application files (WAR files) in the &lt;tomcat_home&gt;/webapps directory (e.g., /usr/share/tomcat7/webapps). Your instance of Tomcat may be configured to look in a different directory. We will refer to the Tomcat application directory as &lt;tomcat_app_dir&gt;.  NOTE: The name of the WAR file (e.g., metacat.war) provides the application context, which appears in the URL of the Metacat (e.g., <a class="reference external" href="http://yourserver.com/metacat/">http://yourserver.com/metacat/</a>). To change the context, simply change the name of the WAR file to the desired name before copying it.  To install the Metacat WAR:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo cp &lt;metacat_package_dir&gt;/metacat.war &lt;tomcat_app_dir&gt;
sudo cp &lt;metacat_package_dir&gt;/metacat-index.war &lt;tomcat_app_dir&gt;
sudo cp &lt;metacat_package_dir&gt;/metacatui.war &lt;tomcat_app_dir&gt;
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="4">
<li>Restart Tomcat. Log in as the user that runs your Tomcat server (often &#8220;tomcat&#8221;) and type:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo /etc/init.d/tomcat7 restart
</pre></div>
</div>
</div></blockquote>
<p>Congratulations! You have now installed Metacat. If everything is installed
correctly, you should see the Authentication Configuration screen (Figure 2.1)
when you type <a class="reference external" href="http://yourserver.com/yourcontext/">http://yourserver.com/yourcontext/</a> (e.g.,
<a class="reference external" href="http://knb.ecoinformatics.org/knb">http://knb.ecoinformatics.org/knb</a>) into a browser. For more information about
configuring Metacat, please see the Configuration Section.</p>
<div class="figure align-center" id="id8">
<img alt="_images/image009.png" src="_images/image009.png" />
<p class="caption"><span class="caption-text">The Authentication Configuration screen appears the first time you open a
new installation of Metacat.</span></p>
</div>
</div>
<div class="section" id="upgrade-metacat">
<h4><a class="toc-backref" href="#id25">4.2.4.2. Upgrade Metacat</a><a class="headerlink" href="#upgrade-metacat" title="Permalink to this headline">¶</a></h4>
<p>To upgrade an existing binary Metacat installation follow the steps in this
section. The steps for upgrading Metacat from source are the same as the
instructions for installing from source:</p>
<ol class="arabic simple">
<li>Download and extract the new version of Metacat. For more information about downloading and extracting Metacat, please see Downloading Metacat.</li>
<li>Stop running Metacat. To stop Metacat, log in as the user that runs your Tomcat server (often &#8220;tomcat&#8221;) and type:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>/etc/init.d/tomcat7 stop
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="3">
<li>Back up the existing Metacat installation. Although not required, we highly recommend that you back up your existing Metacat to a backup directory (&lt;backup_dir&gt;) before installing a new one. You can do so by typing:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>cp &lt;web_app_dir&gt;/metacat &lt;backup_dir&gt;/metacat.&lt;yyyymmdd&gt;
cp &lt;web_app_dir&gt;/metacat.war &lt;backup_dir&gt;/metacat.war.&lt;yyyymmdd&gt;
</pre></div>
</div>
<p>Warning: Do not backup the files to the <code class="docutils literal"><span class="pre">&lt;web_app_dir&gt;</span></code> directory.  Tomcat will
try to run the backup copy as a service.</p>
</div></blockquote>
<ol class="arabic simple" start="4">
<li>Copy the new Metacat WAR file in to the Tomcat applications directory:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo cp &lt;metacat_package_dir&gt;/metacat.war &lt;tomcat_app_dir&gt;
</pre></div>
</div>
<p>Note: Typically, Tomcat will look for its application files (WAR files) in the
<code class="docutils literal"><span class="pre">&lt;tomcat_home&gt;/webapps</span></code> directory. Your instance of Tomcat may be configured to
look in a different directory.</p>
</div></blockquote>
<ol class="arabic simple" start="5">
<li>If you have been (or would like to start) running an LSID server, copy the new authority.war file to the Tomcat applications directory. For more information about the LSID server, please see Optional Installation Options.</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo cp &lt;metacat_package_dir&gt;/authority.war &lt;tomcat_app_dir&gt;
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="6">
<li>Restart Tomcat (and Apache if you have Tomcat integrated with it). Log in as the user that runs your Tomcat server (often &#8220;tomcat&#8221;), and type:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>/etc/init.d/tomcat7 restart
</pre></div>
</div>
</div></blockquote>
<p>7. Run your new Metacat servlet. Go to a Web browser and visit your installed
Metacat application, using a URL of the form:</p>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>http://yourserver.yourdomain.com/yourcontext/
</pre></div>
</div>
</div></blockquote>
<p>You should substitute your context name for &#8220;yourcontext&#8221; in the URL above
(your context will be &#8220;metacat&#8221; unless you change the name of the metacat.war file to
something else). If everything is working correctly, you should be presented
with Metacat&#8217;s Authorization Configuration screen. Note that if you do not have
Tomcat integrated with Apache you will probably have to type
<a class="reference external" href="http://yourserver.yourdomain.com:8080/yourcontext/">http://yourserver.yourdomain.com:8080/yourcontext/</a></p>
</div>
<div class="section" id="source-install-and-upgrade">
<h4><a class="toc-backref" href="#id26">4.2.4.3. Source Install and Upgrade</a><a class="headerlink" href="#source-install-and-upgrade" title="Permalink to this headline">¶</a></h4>
<p>Whether you are building Metacat from the source distribution or source code
checked out from SVN, you will need Apache Ant to do the build (see Installing
and Configuring Required Software for more information about Ant).</p>
<p>To install Metacat from source:</p>
<ol class="arabic simple">
<li>Edit the build.properties file found in the directory in which you
downloaded Metacat. Note: Throughout the instructions, we will refer to this
directory as <code class="docutils literal"><span class="pre">&lt;metacat_src_dir&gt;</span></code>.</li>
</ol>
<blockquote>
<div><ul class="simple">
<li>Set the build.tomcat.dir property to your Tomcat installation directory.
Metacat will use some of the native Tomcat libraries during the build. For
instance: build.tomcat.dir=/usr/local/tomcat</li>
<li>Set the app.deploy.dir property to your application deployment directory.
For instance: app.deploy.dir=/usr/local/tomcat/webapps</li>
</ul>
</div></blockquote>
<ol class="arabic simple" start="2">
<li>In the <code class="docutils literal"><span class="pre">&lt;metacat_src_dir&gt;</span></code>, run:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo ant clean install
</pre></div>
</div>
<p>You will see the individual modules get built. You should see a &#8220;BUILD
SUCCESSFUL&#8221; message at the end.</p>
<p>You should see a new file named metacat.war in your application deployment
directory.</p>
</div></blockquote>
<p>To run your new Metacat servlet, open a Web browser and type:</p>
<div class="highlight-python"><div class="highlight"><pre>http://yourserver.yourdomain.com/yourcontext/
(e.g.  http://knb.ecoinformatics.org/metacat/)
</pre></div>
</div>
<p>Your context will be &#8220;metacat&#8221; unless you changed the name of the metacat.war file to
something else. The servlet may require a few seconds to start up, but once it
is running, you will be presented with the Authorization Configuration screen.</p>
</div>
</div>
<div class="section" id="optional-installation-options-lsid-server">
<h3><a class="toc-backref" href="#id27">4.2.5. Optional Installation Options (LSID Server)</a><a class="headerlink" href="#optional-installation-options-lsid-server" title="Permalink to this headline">¶</a></h3>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The support for LSID identifiers is deprecated, and is being replaced with
support for <a class="reference external" href="http://www.doi.org/">DOI</a> identifiers in a future release. We are maintaining support
for LSIDs on one particular site, but this support will be removed in a
future version of Metacat.</p>
</div>
<p>Metacat&#8217;s optional LSID server allows Metacat to use a standardized syntax for
identifying data sets, in addition to Metacat&#8217;s internal, custom scheme for
identifiers. LSID&#8217;s were designed to identify complex biological entities with
short identifiers (much like DOIs in publishing) that are both computer and
human readable. LSID identifiers are URIs and are therefore usable in many
Internet applications, but they also cleanly separate the identity of a data
set (i.e., its permenant identifier) from its current location (e.g., the list
of URLs from which it might be retrieved).  LSIDs accomplish this by using a
level of indirection; the identifier represents simply a name without location,
but an associated resolver service can be used to locate the current location
of the data and medata for the data set.  This is accomplished by establishing
a well-known location for the resolution service for each authority using an
infrequently used feature of the domain name system called SRV records.  At its
most basic, resolution of an identifier is performed when a client looks up the
SRV record for an LSID by querying DNS, which returns the current host and port
of the authority web service, which is in turn used to locate the data and
metadata.</p>
<p>Using LSIDs to identify data records is being debated among members of the
Taxonomic Databases Working Group (TDWG).  There are several alternate
technologies that are under consideration (e.g., <a class="reference external" href="http://www.doi.org/">DOI</a>, plain http URIs), and so
at this time the support for LSIDs in Metacat has been created on an
experimental basis only.  If the LSID approach is ratified by the broader
community, we will expand support for LSIDs in Metacat, but until then it is an
optional and experimental feature.</p>
<p>The format of an LSID is:</p>
<div class="highlight-python"><div class="highlight"><pre>urn:lsid:&lt;Authority&gt;:&lt;Namespace&gt;:&lt;ObjectID&gt;[:&lt;Version&gt;]
e.g., urn:lsid:ecoinformatics.org:tao:12039:1
</pre></div>
</div>
<p>When you enable the Metacat LSID support, you can use LSID clients (such as
LSID Launchpad) and LSID notation to query Metacat for data and metadata. LSID
notation can be used directly in Metacat HTTP queries as well. For example, a
data package with an ID tao.12039.1 that is stored in a Metacat available at:
<a class="reference external" href="http://example.com:9999">http://example.com:9999</a> can be accessed by the following HTTP Metacat queries:</p>
<div class="highlight-python"><div class="highlight"><pre>http://example.com:9999/authority/data?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
(To return the data)

http://example.com:9999/authority/metadata?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
(To return the metadata)
</pre></div>
</div>
<p>Notice that in the HTTP query strings, the periods in the data package ID have
been replaced with colons. The authority (ecoinformatics.org) must be properly
configured by the Metacat administrator. Note: In order to configure the
authority, you must have access to the DNS server for the Metacat domain.
Further instructions are provided below.</p>
<div class="section" id="install-and-configure-the-lsid-server-shipped-with-metacat">
<h4><a class="toc-backref" href="#id28">4.2.5.1. Install and configure the LSID Server shipped with Metacat</a><a class="headerlink" href="#install-and-configure-the-lsid-server-shipped-with-metacat" title="Permalink to this headline">¶</a></h4>
<p>To install the LSID server using the binary installation:</p>
<ol class="arabic simple">
<li>Copy the authority.war file to Tomcat:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo cp &lt;metacat_package_directory&gt;/authority.war /usr/share/tomcat7/webapps
</pre></div>
</div>
</div></blockquote>
<ol class="arabic" start="2">
<li><p class="first">Set up the LSID server by dropping the authority file into Apache&#8217;s
sites-available directory and running a2ensite to enable the site:</p>
<div class="highlight-python"><div class="highlight"><pre>sudo cp &lt;metacat_helper_dir&gt;/authority /etc/apache2/sites-available
sudo a2ensite authority
</pre></div>
</div>
</li>
<li><p class="first">Restart Tomcat. Log in as the user that runs your Tomcat server (often
&#8220;tomcat&#8221;) and type:</p>
<div class="highlight-python"><div class="highlight"><pre>/etc/init.d/tomcat5.5 restart
</pre></div>
</div>
</li>
<li><p class="first">Restart Apache to bring in changes by typing:</p>
</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo /etc/init.d/apache2 restart
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="5">
<li>See notes beneath LSID server source installation for instructions for
modifying the SRV record(s)</li>
</ol>
</div>
<div class="section" id="to-install-the-lsid-server-from-a-source">
<h4><a class="toc-backref" href="#id29">4.2.5.2. To install the LSID server from a source</a><a class="headerlink" href="#to-install-the-lsid-server-from-a-source" title="Permalink to this headline">¶</a></h4>
<ol class="arabic simple">
<li>In the build.properties file found in the directory into which you
extracted the Metacat source code, set the authority and config.lsidauthority
properties. For example:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre><span class="n">authority</span><span class="o">.</span><span class="n">context</span><span class="o">=</span><span class="n">authority</span>
<span class="n">config</span><span class="o">.</span><span class="n">lsidauthority</span><span class="o">=</span><span class="n">ecoinformatics</span><span class="o">.</span><span class="n">org</span>
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="2">
<li>In the &lt;metacat-src-dirctory&gt; create the authority.war by running:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo ant war-lsid
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="3">
<li>Copy the LSID WAR file into the Tomcat application directory.</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo cp &lt;metacat_package_dir&gt;/dist/authority.war &lt;tomcat_app_dir&gt;
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="4">
<li>Restart Tomcat. Log in as the user that runs your Tomcat server (often
&#8220;tomcat&#8221;) and type:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>/etc/init.d/tomcat7 restart
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="5">
<li>If you are running Tomcat behind the Apache server (the recommended
configuration), set up and enable the authority service site configurations by
typing:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo cp &lt;metacat_helper_dir&gt;/authority &lt;apache_install_dir&gt;/sites-available
sudo a2ensite authority
</pre></div>
</div>
<p>Where &lt;metacat_helper_dir&gt; can be found in &lt;metacat_code_dir&gt;/src/scripts</p>
</div></blockquote>
<ol class="arabic simple" start="6">
<li>Restart Apache to bring in changes by typing:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo /etc/init.d/apache2 restart
</pre></div>
</div>
<p>Once the authority.war is installed, you must also modify the SRV record(s)
on the DNS server for the domain hosting the Metacat. The record should be
added to the master zone file for the metacat&#8217;s DNS server:</p>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>_lsid._tcp      IN      SRV     1       0       8080    &lt;metacat.edu&gt;.
</pre></div>
</div>
</div></blockquote>
<p>Where &lt;metacat.edu&gt; is the name of the machine that will serve as the
physical location of the AuthorityService.</p>
<p>For example, the value of &lt;metacat.edu&gt; for the below example URL would be
example.com:</p>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>http://example.com:9999/authority/data?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
</pre></div>
</div>
</div></blockquote>
<p>For more information, please see <a class="reference external" href="http://www.ibm.com/developerworks/opensource/library/os-lsid/">http://www.ibm.com/developerworks/opensource/library/os-lsid/</a></p>
</div></blockquote>
</div>
</div>
<div class="section" id="troubleshooting">
<h3><a class="toc-backref" href="#id30">4.2.6. Troubleshooting</a><a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h3>
<p>We keep and update a list of common problems and their solutions on the KNB
website. See <a class="reference external" href="http://knb.ecoinformatics.org/software/metacat/troubleshooting.html">http://knb.ecoinformatics.org/software/metacat/troubleshooting.html</a>
for more information.</p>
</div>
</div>
<div class="section" id="installing-on-windows">
<h2><a class="toc-backref" href="#id31">4.3. Installing on Windows</a><a class="headerlink" href="#installing-on-windows" title="Permalink to this headline">¶</a></h2>
<p>Metacat can be installed on Windows. Please follow the instructions in this
section for downloading Metacat, installing the required software, and
installing Metacat. Note that Registry and Data Upload functionality has not
been tested on Windows.</p>
<div class="section" id="download-metacat">
<h3><a class="toc-backref" href="#id32">4.3.1. Download Metacat</a><a class="headerlink" href="#download-metacat" title="Permalink to this headline">¶</a></h3>
<p>To obtain a Metacat WAR file, which is used when installing the Metacat
servlet:</p>
<ol class="arabic simple">
<li>Browse to the KNB Software Download Page. In the Metacat section, select
the link that looks like: metacat-bin-X.X.X.zip, where X.X.X is the latest
version of Metacat (e.g., 2.0.4).</li>
<li>Choose to download and Save the file locally.</li>
<li>Extract the Metacat package files using your Windows zip utility. You
should see a WAR file and several supporting files (we will only use the WAR
file when installing Metacat).</li>
</ol>
<p>Note: The location where these files were extracted will be referred to as the
<code class="docutils literal"><span class="pre">&lt;metacat_package_dir&gt;</span></code> for the remainder of this documentation.</p>
<p>Note: Before installing Metacat, please ensure that all required software is
installed and running correctly.</p>
</div>
<div class="section" id="install-required-software">
<h3><a class="toc-backref" href="#id33">4.3.2. Install Required Software</a><a class="headerlink" href="#install-required-software" title="Permalink to this headline">¶</a></h3>
<p>Before you can install and run Metacat, you must ensure that a recent Java SDK,
PostgreSQL and Tomcat are installed, configured, and running correctly.</p>
<ul class="simple">
<li><a class="reference external" href="http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html">Java 8</a></li>
<li><a class="reference external" href="http://tomcat.apache.org/">Apache Tomcat</a></li>
<li><a class="reference external" href="http://www.postgresql.org/">PostgreSQL</a> Database</li>
</ul>
<div class="section" id="id3">
<h4><a class="toc-backref" href="#id34">4.3.2.1. Java 8</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
<p>To run Metacat, you must have Java 8. Make sure that
the JAVA_HOME environment variable is properly set and that both java and javac
are on your PATH.</p>
<p>To download and install Java:</p>
<ol class="arabic simple">
<li>Browse to: <a class="reference external" href="http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html">http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html</a> and follow
the instructions to download JDK 8.</li>
<li>Run the downloaded installer to install Java.</li>
<li>Set the JAVA_HOME environment variable: In &#8220;My Computer&#8221; properties, go to
&#8220;advanced settings &gt; environment variables&#8221;. Add:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>System Variable: JAVA_HOME C:\Program Files\Java\jdk1.8.0_79
(or whichever version you downloaded)
</pre></div>
</div>
</div></blockquote>
</div>
<div class="section" id="id4">
<h4><a class="toc-backref" href="#id35">4.3.2.2. Apache Tomcat</a><a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
<p>We recommend that you install Tomcat version 7.  To download and install Tomcat:</p>
<ol class="arabic simple">
<li>Browse to: <a class="reference external" href="http://tomcat.apache.org/">http://tomcat.apache.org/</a></li>
<li>Download the Tomcat core zip file</li>
<li>Extract Tomcat files to C:Program Filestomcat using the windows zip
utility.</li>
</ol>
</div>
<div class="section" id="id5">
<h4><a class="toc-backref" href="#id36">4.3.2.3. PostgreSQL Database</a><a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h4>
<p>Metacat only can be run with <a class="reference external" href="http://www.postgresql.org/">PostgreSQL</a>. Instructions for installing and
configuring PostgreSQL for use with Metacat are included in this section.</p>
<p>To download and install PostgreSQL:</p>
<ol class="arabic simple">
<li>Browse to <a class="reference external" href="http://www.postgresql.org/download/windows">http://www.postgresql.org/download/windows</a> and download the
one-click installer</li>
<li>Run the installer</li>
<li>Edit C:Program FilesPostgreSQL8.3data and add:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>host metacat metacat 127.0.0.1 255.255.255.255 password
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="4">
<li>Create a super user. At the command line, enter:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>C:\Program Files\PostgreSQL\8.3\bin
createdb -U postgres metacat (enter super user password)
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="5">
<li>Log in to PostgreSQL:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>psql -U postgres metacat (enter super user password)
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="6">
<li>Create a Metacat user:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>CREATE USER metacat WITH UNENCRYPTED PASSWORD &#39;your_password&#39;
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="7">
<li>Exit PostgreSQL:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>\q
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="8">
<li>Restart PostgreSQL from the start menu by selecting:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>run start/All Programs/PostgreSQL 8.3/Stop Server
run start/All Programs/PostgreSQL 8.3/Start Server
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="9">
<li>Test the installation by logging in as the metacat user:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>psql -U metacat -W -h localhost metacat
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="10">
<li>Exit PostgreSQL:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>\q
</pre></div>
</div>
</div></blockquote>
<p>The Metacat servlet automatically creates the required database schema. For
more information, please see Database Configuration.</p>
</div>
</div>
<div class="section" id="id6">
<h3><a class="toc-backref" href="#id37">4.3.3. Installing Metacat</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h3>
<p>Instructions for a new install and for an upgrade are included below.</p>
<div class="section" id="id7">
<h4><a class="toc-backref" href="#id38">4.3.3.1. New Install</a><a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h4>
<p>Before installing Metacat, please ensure that all required applications are
installed, configured to run with Metacat, and running correctly. If you are
upgrading an existing Metacat servlet, please skip to Upgrade.</p>
<p>To install a new Metacat servlet:</p>
<ol class="arabic simple">
<li>Create the Metacat base directory at:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>C:/Program Files/metacat
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="2">
<li>Copy the Metacat WAR file to Tomcat (for information about obtaining a
Metacat WAR file, see Download Metacat):</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>copy &lt;metacat_package_dir&gt;\metacat.war C:\Program Files\tomcat\webapps
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="3">
<li>Restart Tomcat:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>C:\Program Files\tomcat\shutdown.bat
C:\Program Files\tomcat\startup.bat
</pre></div>
</div>
</div></blockquote>
<p>Congratulations! You are now ready to configure Metacat. Please see the
Configuration Section for more information.</p>
</div>
<div class="section" id="upgrade">
<h4><a class="toc-backref" href="#id39">4.3.3.2. Upgrade</a><a class="headerlink" href="#upgrade" title="Permalink to this headline">¶</a></h4>
<p>To upgrade an existing Metacat installation:</p>
<ol class="arabic simple">
<li>Download and extract the new version of Metacat. For more information about
downloading and extracting Metacat, please see Download Metacat.</li>
<li>Back up the existing Metacat installation. Although not required, we highly
recommend that you back up your existing Metacat to a backup directory
(&lt;backup_dir&gt;) before installing a new version. You can do so by copying:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>&lt;web_app_dir&gt;/metacat to &lt;backup_dir&gt;/metacat.&lt;yyyymmdd&gt;
&lt;web_app_dir&gt;/metacat.war to &lt;backup_dir&gt;/metacat.war.&lt;yyyymmdd&gt;
</pre></div>
</div>
<p>Warning: Do not backup the metacat directory in the &lt;web_app_dir&gt; directory.
Tomcat will try to run the backup copy as a service.</p>
</div></blockquote>
<ol class="arabic simple" start="3">
<li>Copy the new Metacat WAR file in to Tomcat applications directory:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>copy metacat.war C:\Program Files\tomcat\webapps
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="4">
<li>Restart Tomcat:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>C:\Program Files\tomcat\shutdown.bat
C:\Program Files\tomcat\startup.bat
</pre></div>
</div>
</div></blockquote>
<p>Congratulations! You are now ready to configure Metacat. Please see Configuring
Metacat for more information.</p>
</div>
</div>
</div>
</div>


	          </div>
	        </div>
      	</div>

	
	      <div class="clearer"></div>
	    </div>
	    <div class="footer">
	    	<div class="footerNav">
				
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right">
        <span id="searchbox" style="display: none;">
            <form class="search" action="search.html" method="get">
              <input type="text" name="q" size="18" />
              <input type="submit" value="Go" class="icon-search"/>
              <input type="hidden" name="check_keywords" value="yes" />
              <input type="hidden" name="area" value="default" />
            </form>
        </span>
        </li>
        <script type="text/javascript">$('#searchbox').show(0);</script>
        <li class="right">
          <a href="genindex.html" title="General Index"
             >index</a>
           </li>
        <li class="right">
          <a href="configuration.html" title="5. Configuring Metacat"
             >next</a>
           </li>
        <li class="right">
          <a href="license.html" title="3. License"
             >previous</a>
           </li>
        <li class="breadcrumb first"><a href="index.html">Metacat 2.10.4 documentation</a> &raquo;</li> 
      </ul>
      
    </div>
			</div>
	    	<div class="small-print">
			      &copy; Copyright 2012, Regents of the University of California.
			      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.2.
			</div>
	    </div>
	</div>
  </body>
</html>