.. sectnum::
   :prefix: 2.
   :start: 1

.. footer::

   \- ###Page### -

===============
2. Installation
===============

:Authors: Fred Vos, Sjoerd Schunselaar
:Date: 2010-03-30

Requirements
------------

Operating System
~~~~~~~~~~~~~~~~~

  The software is written in Java and should work in all Operating Systems, but scripts for the command line interface are available only for Unix/Linux at the moment.
  The website can run in any servlet container.

Sun Java \>= 1.5
~~~~~~~~~~~~~~~~~

  You need at least Java 1.5, because of the use of generics.
  Install the JDK (Java Development Kit) if you want to build a package from sources.
  If you want to install and run from compiles packages, installing the JRE (Java Runtime Environment) is enough.

Servlet container
~~~~~~~~~~~~~~~~~

  For the website you need a servlet container, like Apache Tomcat, Jetty of Glassfish.
  During development of the website you can use the Jetty plugin to launch the Jetty servlet container.

Build from sources
-------------------

  Skip this if you want to install a compiled package.

Required software
~~~~~~~~~~~~~~~~~

*Subversion*

  To get connected to the Subversion Repository and be able to checkout the code, a SVN client is required.
  You can download it from .. _Subversion Homepage: http://subversion.tigris.org/ (linux / unix and windows clients) and install it.
  
*Maven2*

  Make sure you have Maven2 installed.
  There is a Debian package 'maven2' available in Ubuntu 8.04.
  See .. _Maven Homepage: http://maven.apache.org for more info on Maven2.

*Apache Tomcat*

  The website can run on different servlet containers. In this example we use Apache Tomcat.
  To get Apache Tomcat go to .. _Apache Homepage: http://tomcat.apache.org/, and get version 5.5.

Get the sources
~~~~~~~~~~~~~~~~~
  
*Subversion*

  As a developer, make sure you get access to the Subversion repository. 
  Send an e-mail message to one of the NEEO contacts at Tilburg University and Tilburg University will send you an e-mail with the details.
  Once you have access to the repository, you can checkout the required code:
  
  - commons-bibl
  - commons-io
  - commons-lang
  - commons-oai
  - commons-xml

*Unix / Linux:*

::

	$ mkdir ~/uvt-dev
	$ cd ~/uvt-dev
	$ svn checkout https://svn.non-gnu.uvt.nl/uvt-dev/trunk/sources/commons/

*Microsoft OS:*

::

	C:\>mkdir uvt-dev
	C:\>cd uvt-dev
	C:\uvt-dev>svn checkout https://svn.non-gnu.uvt.nl/uvt-dev/trunk/sources/commons/

Now we can get NEEO, which contains the NEEO-website and the NEEO-portlet
  
*Unix / Linux:*

::

	$ mkdir ~/uvt-dev
	$ cd ~/uvt-dev
	$ svn checkout https://svn.non-gnu.uvt.nl/uvt-dev/trunk/sources/neeo

*Microsoft OS:*

::

	C:\>mkdir uvt-dev
	C:\>cd uvt-dev
	C:\uvt-dev>svn checkout https://svn.non-gnu.uvt.nl/uvt-dev/trunk/sources/neeo


You can use other directories if you like.
This is just a sample.

*Maven profiles*

Edit or create file ``~/.m2/settings.xml`` and make sure a profile called 'development' is declared and active:

::

 <settings xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
  http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <profiles>
    <profile>
      <id>development</id>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>development</activeProfile>
  </activeProfiles>
 </settings> 

*Build and install commons*

The uvt-commonspackage contains some software that is or can be shared by several projects.
Compile it and install it in your local Maven repository, usually located in <<<$HOME/.m2/repository>>>.
  
  
Assuming the sources of commons are located in directory <<<$HOME/uvt-dev/>>>, the following commands will install commons in your local Maven repository:

::

  $ cd ~/uvt-dev/
  $ mvn install


*Deploy the website*

To get the website running deploy the website with mvn to the webserver, in this example Apache Tomcat.
First check if your webserver is started. Also set the correct parameters in the POM.xml for deploying to the correct server.
  
::

 <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>tomcat-maven-plugin</artifactId>
        <version>1.0-beta-1</version>
        <configuration>
          <url>http://www.mydomain.com:1234/mymanager</url>
        </configuration>
      </plugin>


If you want to set the correct user credentials for Apache Tomcat set this in your POM.xml and add a settings.xml file.
  
``POM.xml``:
  	
::

 	<plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>tomcat-maven-plugin</artifactId>
        <version>1.0-beta-1</version>
        <configuration>
          <server>myserver</server>
        </configuration>
      </plugin>

``settings.xml``:
	
::

	<settings>
	  <servers>
		<server>
    	  <id>myserver</id>
	        <username>myusername</username>
      		<password>mypassword</password>
    	</server>
	  </servers>
	</settings>

After these optional changes, the website can be deployed with the following command (in <<<$HOME/uvt-dev/neeo/neeo-website>>>).

``mvn tomcat:deploy``

Now the website is running (default on ``http://127.0.0.1:8080/neeo-website``).

*Deploy the services*

To deploy the services use the steps described in 'Deploy the website'. Instead of 'neeo-website' use 'neeo-services'.

Generate Tarballs
~~~~~~~~~~~~~~~~~

At this moment tarballs are used for Debian packaging. To create a tarball ready for distribution (including install and build files follow the next steps).

*Neeo-core, Neeo-services and Neeo-website*
  
For those three projects we can use the same command (in the different folders). Go to one of them and execute the following command:
(For sure we included the clean command so the tarball is clean as possible.)


::

  mvn clean javadoc:javadoc assembly:assembly

Generate site
~~~~~~~~~~~~~~~~~

*GraphViz*

Maven can generate Javadoc documentation from the sources.
It uses UMLGraph to generate UML diagrams in the Javadoc pages.
To generate these UML graphs, you need GraphViz.
On a Linux system, this is ususally available as a package.
On a Debian like system (Debian, Ubuntu) try:

  ``$ sudo apt-get-install graphviz``

*Site*

Use the following command 'in' the neeo-core directory:

::

$ mvn site

This should lead to a site with a description of the project, these pages and the Javadoc.
You can find the generated site in the ``target/site`` directory.

Install using generated tarball's
----------------------------------

This example is based on neeo-core.
Eacht Tarball includes several files for building, installing etc.
First you've to untar the tarball, then you can install it with the following instructions:
    
::

  tar -xzvf neeo-core-2.0-SNAPSHOT-bin.tar.gz
  ./clean
  ./configure
  ./build
  ./install