<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
		"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="installation">
<title>Installation</title>

<para>
Before developing an application with @webserv@, it is essential to install <emphasis>@webserv@</emphasis>,
an <emphasis>Integrated Development Environment</emphasis> (IDE), and a build system integrated with Eclipse.
The IDE used here is the
Eclipse-based <emphasis>@sts@</emphasis> (@sts.short@), and 
the build system used here is <emphasis>@maven.full@</emphasis>.
</para>
<para>@sts.short@ is supplied as a fully configured Eclipse IDE, with @virgo@ @webserv@ and @maven@ plugins built-in.</para>

<section id="installation.prereqs">
<title>Pre-requisites</title>

<para>
Before proceeding, ensure that a Java<trademark class="trade"/> Standard Edition Development Kit (JDK)
for Java 6 or later is installed and that the <literal>JAVA_HOME</literal> environment variable 
is set to the root directory of the JDK.
(<emphasis>A Java Runtime Environment (JRE) alone is not sufficient,
a development kit is necessary to use the facilities in @sts.short@.</emphasis>)
</para>

<para>
To verify this, issue the command <literal>"%JAVA_HOME%"\bin\java -version</literal> from
a command prompt on Windows (or <literal>$JAVA_HOME/bin/java -version</literal> from a terminal window on UNIX)
and ensure that the command completes successfully and reports
a Java version <literal>1.6.</literal><emphasis>x</emphasis> (denoting Java 6) or greater.
</para>

<para>
Also issue the command <literal>"%JAVA_HOME%"\bin\jar</literal> to ensure that there is a means of
extracting files from zip archives.
If the <literal>jar</literal> command is unavailable, download and install a suitable zip program
such as <literal>7zip</literal>, <literal>gzip</literal>, or <literal>WinZip</literal>.
This is most relevant for Windows operating systems where the inbuilt zip extraction utility may
not handle long pathnames correctly.
</para>

</section>

<section id="installation.dmserver">

<title>Installing @webserv@</title>

<para>
Although the steps are similar, the details of installing the @virgo@ @webserv@
depend on the operating system.
</para>

<para>
Obtain @webserv@ from the 
download site (<ulink url="@webserv.download.url@">@webserv.download.url@</ulink>).
This guide is consistent with version @webserv.version@ of @webserv@.
</para>

<section>

<title>Installing @webserv@ on Windows<trademark class="trade"/> operating systems</title>

<para>
Unzip the download of @webserv@ to the root directory of
a drive (this will avoid possible problems with long pathnames).
Set an environment variable <literal>%VWS_HOME%</literal> to refer to the unzipped folder…
<programlisting>prompt> cd C:\
prompt> "%JAVA_HOME%"\bin\jar xf <emphasis>\path\to\</emphasis>@webserv.zip.file@
prompt> set VWS_HOME=C:\@webserv.expanded.dir@
</programlisting>
</para>

<para>
To verify the installation, issue the command:
<literal>"%VWS_HOME%"\bin\startup.bat</literal> and ensure a message numbered <literal>UR0001I</literal> 
is displayed.
Many other messages about starting and installing other required artifacts are produced, 
but the <literal>UR0001I</literal> message indicates that the user region is ready for use.
(<emphasis>Timestamps have been removed
and thread names and other details may vary with different installations and versions.</emphasis>)
<programlisting>system-artifacts             &lt;TC0000I&gt; Starting Tomcat. 
system-artifacts             &lt;TC0010I&gt; Creating HTTP/1.1 connector with scheme http on port 8080. 
system-artifacts             &lt;TC0010I&gt; Creating HTTP/1.1 connector with scheme https on port 8443. 
system-artifacts             &lt;TC0010I&gt; Creating AJP/1.3 connector with scheme http on port 8009.
system-artifacts             &lt;TC0001I&gt; Started Tomcat. 
system-artifacts             &lt;DE0004I&gt; Starting bundle 'org.eclipse.virgo.web.core' version '2.1.0.RELEASE'. 
system-artifacts             &lt;DE0004I&gt; Starting bundle 'org.eclipse.virgo.web.dm' version '2.1.0.RELEASE'. 
start-signalling-1           &lt;DE0005I&gt; Started bundle 'org.eclipse.virgo.web.dm' version '2.1.0.RELEASE'. 
system-artifacts             &lt;DE0005I&gt; Started bundle 'org.eclipse.virgo.web.tomcat' version '2.1.0.RELEASE'. 
start-signalling-1           &lt;DE0005I&gt; Started bundle 'org.eclipse.gemini.web.tomcat' version '1.1.0.RELEASE'. 
start-signalling-2           &lt;DE0005I&gt; Started bundle 'org.eclipse.virgo.web.core' version '2.1.0.RELEASE'. 
start-signalling-2           &lt;DE0005I&gt; Started plan 'org.eclipse.virgo.web' version '2.1.0'. 
Thread-2                     &lt;UR0001I&gt; User region ready. </programlisting>
</para>
<para>Shut down the server by pressing <literal>Ctrl-C</literal>.
</para>

</section>

<section>

<title>Installing @webserv@ on UNIX<trademark class="trade"/> operating systems</title>

<para>
    Unzip the download of @webserv@ to a suitable location on the file system, such
    as the home directory. (If the download was automatically unzipped by the operating
    system, simply move the unzipped directory to the chosen location.)
    Set an environment variable <literal>$VWS_HOME</literal> to refer to the unzipped folder…
<programlisting>prompt$ mkdir <emphasis>/path/to/home/</emphasis>springsource
prompt$ cd <emphasis>/path/to/home/</emphasis>springsource
prompt$ unzip <emphasis>/path/to/</emphasis>@webserv.zip.file@
prompt$ export VWS_HOME=<emphasis>/path/to/home/</emphasis>springsource/@webserv.expanded.dir@
</programlisting>
</para>

<para>
To verify the installation, use a terminal window to issue the command:
<literal>$VWS_HOME/bin/startup.sh</literal> and ensure a message numbered <literal>UR0001I</literal> is displayed.
Many other messages about starting and installing other required artifacts are produced,
but the <literal>UR0001I</literal> message indicates that the user region is ready for use.
(<emphasis>Timestamps have been removed
and thread names and other details may vary with different installations and versions.</emphasis>)
<programlisting>system-artifacts             &lt;TC0000I&gt; Starting Tomcat. 
system-artifacts             &lt;TC0010I&gt; Creating HTTP/1.1 connector with scheme http on port 8080. 
system-artifacts             &lt;TC0010I&gt; Creating HTTP/1.1 connector with scheme https on port 8443. 
system-artifacts             &lt;TC0010I&gt; Creating AJP/1.3 connector with scheme http on port 8009.
system-artifacts             &lt;TC0001I&gt; Started Tomcat. 
system-artifacts             &lt;DE0004I&gt; Starting bundle 'org.eclipse.virgo.web.core' version '2.1.0.RELEASE'. 
system-artifacts             &lt;DE0004I&gt; Starting bundle 'org.eclipse.virgo.web.dm' version '2.1.0.RELEASE'. 
start-signalling-1           &lt;DE0005I&gt; Started bundle 'org.eclipse.virgo.web.dm' version '2.1.0.RELEASE'. 
system-artifacts             &lt;DE0005I&gt; Started bundle 'org.eclipse.virgo.web.tomcat' version '2.1.0.RELEASE'. 
start-signalling-1           &lt;DE0005I&gt; Started bundle 'org.eclipse.gemini.web.tomcat' version '1.1.0.RELEASE'. 
start-signalling-2           &lt;DE0005I&gt; Started bundle 'org.eclipse.virgo.web.core' version '2.1.0.RELEASE'. 
start-signalling-2           &lt;DE0005I&gt; Started plan 'org.eclipse.virgo.web' version '2.1.0'. 
Thread-2                     &lt;UR0001I&gt; User region ready. </programlisting>
</para>
<para>Shut down the server by pressing <literal>Ctrl-C</literal>. </para>

</section>
</section>

<section id="installation.sts">
<title>Installing the @sts@</title>

<para>
The @sts@ (@sts.short@) is a development environment based on Eclipse that
is already configured with
<!--comes configured with all-->
the plugins needed to 
work with @webserv@ and OSGi. 
Although the steps are similar, the details of installing @sts.short@ depend on the operating system.
</para>

<para>
Go to the @sts.short@ download site (<ulink url="@sts.download@">@sts.download@</ulink>)
and download the variant appropriate to the operating system being used.
This guide is consistent with @sts.short@ version @sts.version@. Previous versions may not work properly with
the latest revision of @greenpages@, currently @greenpages.version@.
</para>

<para>
It is possible to use vanilla Eclipse, and add the @dmst@ to it.  Please refer to the installation instructions in the
<ulink url="http://www.eclipse.org/virgo/documentation/">Virgo Programmer Guide</ulink>.
</para>

<section>

<title>Installing @sts.short@ on Windows<trademark class="trade"/> operating systems</title>

<para>
Unzip the download of @sts.short@ to the root directory of
a drive (this will avoid possible problems with long pathnames).
<programlisting>prompt> cd C:\
prompt> "%JAVA_HOME%"\bin\jar xf \<emphasis>full…path…to</emphasis>\@sts.zip.file.windows@
</programlisting>
</para>

<para>
To verify the installation, run the <literal>eclipse.exe</literal> (or <literal>sts.exe</literal>) executable in the unzipped directory
and check that @sts.short@ displays a welcome panel. 
The first time there may be a short delay due to the initial set-up of indexes.
</para>

<section>

<title>Installing @sts.short@ on UNIX<trademark class="trade"/> operating systems</title>

<para>
Unpack the download of @sts.short@ to a suitable location on the file system, such
as <literal>/opt</literal> or, if root access is not available, the home directory.
(If the download was automatically unpacked by the operating
system, simply move the unpacked directory to the chosen location.)
</para>

<para>
To verify the installation, run the @sts.short@ executable (<literal>STS.app</literal> on Mac OS X) 
in the unpacked directory and check that @sts.short@ displays a welcome panel.
The first time there may be a short delay due to the initial set-up of indexes.
</para>

</section>

</section>

<section>
<title>Note about Java versions in @sts.short@</title>
<para>
    @sts@ runs on Eclipse using Java Version 1.6, and @webserv@ requires Java Version 1.6. 
    The @greenpages@ application built here also requires Java Version 1.6.
    The default Java compiler settings in @sts.short@ should not need adjusting, but should be checked.
</para>

</section>
</section>

<section id="installation.maven">
<title>Installing @maven.full@</title>

<para>
<emphasis>@maven.full@</emphasis>, or @maven@ for short, is a software project management and comprehension tool
which uses a central <emphasis>Project Object Model</emphasis> (POM) to manage a project&rsquo;s build, reporting 
and documentation generation. POM files (<literal>pom.xml</literal>) are included in the projects for
@greenpages@.
</para>

<para>
To install @maven@, visit the @maven@ website (<ulink url="@maven.url@">@maven.url@</ulink>) 
and follow the download instructions from there.
This document has been written and tested with @maven@ version @maven.version@. The rest of the document 
assumes that @maven@ 
commands (<literal>mvn …</literal>) are available from the command line.
</para>
</section>

</chapter>