aboutsummaryrefslogtreecommitdiffstats
blob: 004d554163ef583518baf1f265479623c57e6bec (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
<?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.
You will see many other messages about starting and installing other required artifacts, 
but the <literal>UR0001I</literal> message indicates that the user region is ready for your 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.
You will see many other messages about starting and installing other required artifacts,
but the <literal>UR0001I</literal> message indicates that the user region is ready for your 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>
If you prefer to use vanilla Eclipse, 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.
    You should not need to alter the default Java compiler settings in @sts.short@ before proceeding.
</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>