Appendix: Deploying Metacat as a Member Node
==================================


About
~~~~~

The :term:`Metacat` Server supports the `DataONE Member Node API`_ and can be used as a general data and metadata repository.  The installation instructions below are fairly specific to a DataONE installation in that configurations are tailored to DataONE systems.  However, it also provides a fairly bare-bones recipe that can adapted for any installation.  Detailed Metacat installation instructions are available at the `KNB site`_. These instructions are oriented toward an Ubuntu 10.04 LTS installation.

Installation
~~~~~~~~~~~~

1. Update the base system software
----------------------------------

::

    $ sudo apt-get update
    $ sudo apt-get dist-upgrade


2. Install prerequisite software
--------------------------------

2.1 Install Java from the DataONE repo
--------------------------------------

Java can also be installed (perhaps preferentially) from the Oracle site, but this provides a Debian package.

::

    $ sudo vim /etc/apt/sources.list
    (add the following lines)
    # Java repository from DataONE
    deb http://dev-testing.dataone.org/ubuntu-java lucid universe

    $ sudo apt-get update
    $ sudo apt-get install --no-install-recommends sun-java6-jdk

2.2 Install Ant, Apache2, Tomcat, PostgreSQL
--------------------------------------------

::

    $ sudo apt-get install --no-install-recommends ant apache2 libapache2-mod-jk \
    tomcat6 postgresql-8.4 postgresql-client-8.4
    $ sudo update-alternatives --config java

2.3 Install Metacat
-------------------

This can be replaced by a tagged release version of the Metacat software if desired.

::

    $ mkdir -p /usr/share/metacat_build/
    $ cd /usr/share/metacat_build/
    $ sudo svn co https://code.ecoinformatics.org/code/metacat/branches/METACAT_2_0_5_BRANCH/
    $ sudo ln -s METACAT_2_0_5_BRANCH/ metacat
    $ sudo ant clean distbin
    $ sudo cp /usr/share/metacat_build/metacat/dist/knb.war /var/lib/tomcat6/webapps/
    $ sudo chown -R tomcat6:tomcat6 /var/lib/tomcat6



Configuration
~~~~~~~~~~~~~

3.1 Configure UFW
-----------------
::

    $ sudo ufw allow ssh
    $ sudo ufw allow http
    $ sudo ufw allow https
    $ sudo ufw enable

3.2 Configure Apache and server-side SSL
----------------------------------------
::

    $ sudo /etc/init.d/apache2 stop
    $ cd /etc/ssl/certs
    $ sudo curl -O https://repository.dataone.org/software/tools/trunk/ca/DataONECAChain.crt
    $ sudo scp username@cn-orc|ucsb|unm-1.dataone.org:geotrust_intermediate.crt .
    $ sudo scp username@cn-orc|ucsb|unm-1.dataone.org:_.dataone.org.crt .
    $ sudo c_rehash # not really needed, but good practice
    $ sudo su
    $ cd ../private
    # scp username@cn-orc|ucsb|unm-1.dataone.org:dataone_org.key  .
    # chgrp ssl-cert dataone_org.key
    # exit
    $ cd /etc/apache2/sites-available/
    $ sudo vim knb
    Add:
    NameVirtualHost *:80
    <VirtualHost *:80>
        ServerAdmin coredev@dataone.org
        ServerName ${hostname}.dataone.org # change this
        DocumentRoot /var/lib/tomcat6/webapps/knb

        <Directory />
            Options FollowSymLinks
            AllowOverride None
        </Directory>

        ErrorLog /var/log/apache2/error.log
        LogLevel warn
        CustomLog /var/log/apache2/access.log combined

        <IfModule mod_jk.c>
            JkMount /knb ajp13
            JkMount /knb/* ajp13
            JkMount /knb/metacat ajp13
            JkMount /*.jsp ajp13
            JkUnMount /knb/cgi-bin/* ajp13
        </IfModule>
    </VirtualHost>

    $ sudo cp knb knb-ssl
    $ sudo vim knb-ssl
    Add:
    <IfModule mod_ssl.c>
    NameVirtualHost *:443
    <VirtualHost *:443>
        ServerAdmin coredev@dataone.org
        ServerName ${hostname}.dataone.org # change this
        DocumentRoot /var/lib/tomcat6/webapps/knb

        <Directory />
            Options FollowSymLinks
            AllowOverride None
        </Directory>
        <Directory /var/lib/tomcat6/webapps/knb/>
            Options Indexes FollowSymLinks MultiViews
            AllowOverride None
            Order allow,deny
            allow from all
        </Directory>

        ErrorLog /var/log/apache2/error.log
        LogLevel warn
        CustomLog /var/log/apache2/access.log combined

        <IfModule mod_jk.c>
            JkMount /knb ajp13
            JkMount /knb/* ajp13
            JkMount /knb/metacat ajp13
            JkMount /*.jsp ajp13
            JkUnMount /knb/cgi-bin/* ajp13
            JkOptions +ForwardURICompatUnparsed
        </IfModule>

        AllowEncodedSlashes On
        AcceptPathInfo      On

        SSLEngine on
        SSLOptions +StrictRequire +StdEnvVars +ExportCertData
        SSLVerifyClient optional
        SSLVerifyDepth  10
        SSLCertificateFile      /etc/ssl/certs/_.dataone.org.crt
        SSLCertificateKeyFile   /etc/ssl/private/dataone_org.key
        SSLCertificateChainFile /etc/ssl/certs/geotrust_intermediate.crt
        SSLCACertificateFile    /etc/ssl/certs/DataONECAChain.crt
    </VirtualHost>
    </IfModule>

    $ sudo a2enmod ssl
    $ sudo a2enmod deflate
    $ sudo a2ensite knb
    $ sudo a2ensite knb-ssl
    $ sudo a2dissite default
    $ sudo a2dissite default-ssl

3.3 Configure the JK Apache to Tomcat connector
-----------------------------------------------
::

    $ cd /etc/apache2
    $ sudo cp /usr/share/metacat_build/metacat/src/scripts/debian/jk.conf mods-available
    $ sudo cp /usr/share/metacat_build/metacat/src/scripts/debian/workers.properties .
    $ vim workers.properties
    Set:
    workers.tomcat_home=/var/lib/tomcat6
    workers.java_home=/usr/lib/jvm/java-6-sun
    $ vim mods-available/jk.conf
    Ensure properties are correct
    $ sudo a2enmod jk
    $ cd /var/lib/tomcat6/conf
    $ sudo vim server.xml
    Uncomment the port 8009 Connector
    $ sudo /etc/init.d/apache2 restart

3.4 Configure Tomcat
--------------------

::

    $ sudo vim /etc/tomcat6/catalina.properties
    Add:
    # DataONE-specific properties
    org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
    org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true
    $ sudo /etc/init.d/tomcat6 restart


3.5 Configure PostgreSQL
------------------------

::

    $ sudo su - postgres
    $ psql metacat
    # CREATE USER metacat UNENCRYPTED PASSWORD 'metacat'; # or a secure password for production
    # \q
    $ createdb -O metacat metacat
    $ vim /etc/postgresql/8.4/main/pg_hba.conf
    Add: "host metacat metacat 127.0.0.1/32 password"
    $ exit
    $ sudo /etc/init.d/postgresql-8.4 restart
    $ psql -U metacat -W -h localhost metacat # test it
    => \q

3.6 Configure Metacat
---------------------

::

    $ cd /var/lib/tomcat6/webapps/
    Note: for non-production environments, unpack the war into the knb folder, and edit
    knb/WEB-INF/metacat.properties and set D1Client.CN_URL to a value other than
    https://cn.dataone.org/cn (like cn-dev, cn-sandbox, cn-stage ...)
    $ sudo mkdir -p /var/metacat/{certs,documents,data,inline-data,temporary,expanded-archives}
    $ sudo mv ~/urn\:node\:mn${CAMPUS}1.{key|pem} /var/metacat/certs # get D1 certs from Dave/Matt
    $ cd /var/metacat/certs
    $ sudo cat urn*key >> urn*pem # concatenate the key into the pem file
    $ sudo chown -R tomcat6:tomcat6 /var/metacat
    $ sudo chown -R tomcat6:ssl-cert *key *pem
    $ sudo chmod o-rwx *key *pem # remove world perms for private key files
    $ sudo /etc/init.d/tomcat6 restart

    Go to http://${hostname}.dataone.org/knb/admin to configure Metacat. Once configured:

    $ vim /var/lib/tomcat6/webapps/knb/WEB-INF/metacat.properties
    Set the spatial cache regeneration and spatial option to false.
	Set the D1Client.CN_URL=https://cn-${env}.test.dataone.org for the specific test environment
    unless you're configuring a production Meber Node
    $ sudo /etc/init.d/tomcat6 restart


Operation
~~~~~~~~~

TODO


.. _KNB site: http://knb.ecoinformatics.org/knb/docs/index.html

.. _DataONE Member Node API: mule1.dataone.org/ArchitectureDocs-current/apis/MN_APIs.html