| <?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 <TC0000I> Starting Tomcat. |
| system-artifacts <TC0010I> Creating HTTP/1.1 connector with scheme http on port 8080. |
| system-artifacts <TC0010I> Creating HTTP/1.1 connector with scheme https on port 8443. |
| system-artifacts <TC0010I> Creating AJP/1.3 connector with scheme http on port 8009. |
| system-artifacts <TC0001I> Started Tomcat. |
| system-artifacts <DE0004I> Starting bundle 'org.eclipse.virgo.web.core' version '2.1.0.RELEASE'. |
| system-artifacts <DE0004I> Starting bundle 'org.eclipse.virgo.web.dm' version '2.1.0.RELEASE'. |
| start-signalling-1 <DE0005I> Started bundle 'org.eclipse.virgo.web.dm' version '2.1.0.RELEASE'. |
| system-artifacts <DE0005I> Started bundle 'org.eclipse.virgo.web.tomcat' version '2.1.0.RELEASE'. |
| start-signalling-1 <DE0005I> Started bundle 'org.eclipse.gemini.web.tomcat' version '1.1.0.RELEASE'. |
| start-signalling-2 <DE0005I> Started bundle 'org.eclipse.virgo.web.core' version '2.1.0.RELEASE'. |
| start-signalling-2 <DE0005I> Started plan 'org.eclipse.virgo.web' version '2.1.0'. |
| Thread-2 <UR0001I> 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 <TC0000I> Starting Tomcat. |
| system-artifacts <TC0010I> Creating HTTP/1.1 connector with scheme http on port 8080. |
| system-artifacts <TC0010I> Creating HTTP/1.1 connector with scheme https on port 8443. |
| system-artifacts <TC0010I> Creating AJP/1.3 connector with scheme http on port 8009. |
| system-artifacts <TC0001I> Started Tomcat. |
| system-artifacts <DE0004I> Starting bundle 'org.eclipse.virgo.web.core' version '2.1.0.RELEASE'. |
| system-artifacts <DE0004I> Starting bundle 'org.eclipse.virgo.web.dm' version '2.1.0.RELEASE'. |
| start-signalling-1 <DE0005I> Started bundle 'org.eclipse.virgo.web.dm' version '2.1.0.RELEASE'. |
| system-artifacts <DE0005I> Started bundle 'org.eclipse.virgo.web.tomcat' version '2.1.0.RELEASE'. |
| start-signalling-1 <DE0005I> Started bundle 'org.eclipse.gemini.web.tomcat' version '1.1.0.RELEASE'. |
| start-signalling-2 <DE0005I> Started bundle 'org.eclipse.virgo.web.core' version '2.1.0.RELEASE'. |
| start-signalling-2 <DE0005I> Started plan 'org.eclipse.virgo.web' version '2.1.0'. |
| Thread-2 <UR0001I> 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’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> |
