Deploying a Coordinating Node
=============================

Deploying a coordinating node involves the following steps:

1. Create a virtual machine for hosting the CN services

2. Install the DataONE security certificate

3. Install the cn-buildout packages through using ``apt``

The steps are described in more detail below.


Create a VM for the CN
----------------------

Coordinating nodes are operated as KVM virtual machines. The basic properties
of these VMs are:

.. list-table::
   :widths: 10 15
   :header-rows: 1
   
   * - Property
     - Value
   * - Processors
     - 4
   * - RAM
     - 405884 KB
   * - Disk
     - 400GB
   * - Swap
     - 2GB


The procedure for creating a new CN VM involves:

1. Obtain necessary localized configuration information such as network, DNS,
   and administrative account details.

2. Create the new VM using the appropriately adjusted ``vm-builder`` script (below).

3. Set the VM to automatically start after a hypervisor restart.

4. Start the VM

5. Create additional accounts for administering the node


The vm-builder script for generating a CN VM follows. Note that if building an
Ubuntu 10.04 CN (lucid), it is necessary to add ``partner`` to the list of
components (for Sun Java)::

  sudo ubuntu-vm-builder kvm karmic \
    --arch='amd64'  \
    --cpus='8' \
    --mem='32000'  \
    --rootsize='620000'  \
    --swapsize='2048'  \
    --dest="/kvm/cn-unm-1.dataone.org" \
    --kernel-flavour='server'  \
    --hostname='cn-unm-1'  \
    --domain='dataone.org'  \
    --mirror='http://archive.ubuntu.com/ubuntu'  \
    --components='main,universe,multiverse'  \
    --addpkg ufw \
    --addpkg dnsutils \
    --addpkg curl \
    --addpkg wget \
    --addpkg libnss-ldap \
    --addpkg nscd \
    --addpkg openssh-server \
    --addpkg nano \
    --addpkg man \
    --addpkg acpid \
    --name='Administrator'  \
    --user='localadmin'  \
    --pass='<< PASSWORD >>'  \
    --bridge=br0 \
    --ip='<< IP ADDRESS >>'  \
    --mask='<< NET MASK >>'  \
    --net='<< NETWORK >>'  \
    --bcast='<< BROADCAST >>'  \
    --gw='<< GATEWAY >>'  \
    --dns='<< DNS SERVER >>' \
    --libvirt qemu:///system

After building the VM, start it up and enable the firewall, download the LDAP
TSL key and add the DataONE repository to apt. 

Setup the firewall::

  $ sudo ufw defaults drop
  $ sudo ufw allow ssh
  $ sudo ufw enable

Add the DataONE Hudson repository to apt sources. Edit
``/etc/apt/sources.list`` and add the following to the end for a karmic based
CN::

  deb http://dev-testing.dataone.org/ubuntu karmic universe

or the following for a lucid (10.04) based CN::

  deb http://dev-testing.dataone.org/ubuntu lucid universe

then update and upgrade::

  sudo apt-get update
  sudo apt-get upgrade



Install the DataONE SSL Key
---------------------------

The DataONE SSL key (``dataone_org.key``) needs to be installed to
``/etc/ssl/private`` otherwise Apache will fail to start. A self signed
certificate can be used for testing most aspects of the server.  

The procedure for generating your own self-signed cert

::

  cd
  pwd
    /home/rwaltz
  mkdir ssl
  cd ssl

  openssl genrsa -des3 -out server.key 1024
    Generating RSA private key, 1024 bit long modulus
    ...........................................++++++
    .............++++++
    e is 65537 (0x10001)
    Enter pass phrase for server.key: <type something here and remember it>
    Verifying - Enter pass phrase for server.key: <type something here and remember it>

  chmod 600 server.key
  openssl req -new -key server.key -out server.csr
    Enter pass phrase for server.key: <type something here that you typed above>
    Country Name (2 letter code) [AU]:US
    State or Province Name (full name) [Some-State]:Tennessee
    Locality Name (eg, city) []:Knoxville
    Organization Name (eg, company) [Internet Widgits Pty Ltd]:DataONE.org
    Organizational Unit Name (eg, section) []:
    Common Name (eg, YOUR name) []:cn-dev.dataone.org
    Email Address []:rwaltz@cn-dev

    Please enter the following 'extra' attributes
    to be sent with your certificate request
    A challenge password []: <pressed enter>
    An optional company name []: <pressed enter>

  XXX NOTE that the common name is spurious XXX

  cp server.key server.key.orig
  openssl rsa -in server.key.orig -out server.key
    Enter pass phrase for server.key.orig: <type something here that you typed above>
    writing RSA key

  openssl x509 -req -days 3650 -in server.csr -signkey server.key -out server.crt
    Signature ok
    subject=/C=US/ST=Tennessee/L=Knoxville/O=DataONE.org/CN=cn-dev.utk.edu/emailAddress=rwaltz@cn-dev.utk.edu
    Getting Private key


  sudo cp server.key /etc/ssl/private/dataone_org.key

  sudo cp server.crt /etc/ssl/certs/dataone.org.crt



Install the ``cn-buildout`` Packages
------------------------------------

Fairly straight forward::

  sudo apt-get install dataone-cn-os-core \
    dataone-cn-metacat \
    dataone-cn-mercury \
    dataone-cn-rest-service

.. Note:: 
   Should be able to just apt-get install dataone-cn-rest-service and the rest
   of the packages should be installed but this isn't tested yet.


Updating a CN
-------------

It will be necessary to update the CN software stack on a regular basis while
the CN software stack is under active development. For the most part, this
process should be as simple as the normal installed software update process of::

  sudo apt-get update
  sudo apt-get upgrade

The version information of the cn-buildout packages is automatically updated
as they are built by Hudson_ and so any package updates should be picked up by
``apt``. 

It may be necessary on occasion to perform a more extensive update
that can not be effectively handled through the automated process.
Notification of such situations should be made through the
developers@dataone.org mailing list.



.. _Hudson: http://dev-testing.dataone.org:8080/hudson