Skip to Content
Version 11.1 by Quinton Dolan on 2007/07/14 21:07
Show last authors
1 This article was written by Andrew Lindesay ([[http://www.lindesay.co.nz]]) around May 2005. It first appeared as LaTeX PDF and has been transcribed into this Wiki. You use the information contained in this document at your own risk. Please contact the author if you feel there may have been an error in the conversion to Wiki markup.
2
3 |=Contents
4 |
5
6 {{toc style="disc"}}{{/toc}}
7
8 = Abstract =
9
10 From WebObjects 5.2, it has been possible to derive a build product from a WebObjects application project that can be deployed into a J2EE servlet container. This article shows how it is possible to
11 deploy a WebObjects 5.2 application into a Tomcat environment and achieve a very similar topology to the "native" WebObjects deploy.
12
13 = Introduction =
14
15 This document was originally written assuming a Tomcat 5 deployment, but after some difficulties with web services and AXIS, I have modified this document to also cater for a Tomcat 3 deployment. This document covers both circumstances.
16
17 = Assumptions =
18
19 This article assumes the following:
20
21 * WebObjects 5.2 (likely to work fine with newer versions)
22 * Java 1.4
23 * Latest Tomcat release of version 5 (5.5.12 at the time of writing) or 3 (3.3.2 at the time of writing)
24 * Some sort of UNIX deployment.
25 * The reader has some conception of the concepts behind servlet technology.
26 * The reader is familiar with a standard WebObjects deployment topology which will be referred to as //wotaskd// deployment.
27
28 For the purposes of this document, it is assumed that Tomcat has been installed at a directory on the local disc called ##$TOMCATDIR##. It is also assumed that you will have another directory with the files required to configure and run an instance called ##$INSTDIR##. It is assumed also that you will have a directory called ##$JKDIR## with the Tomcat apache adaptor in it. In this article, some configuration files require the paths to be shown and these are tabulated below.
29
30 | ##$TOMCATDIR## | ##/opt/tomcat##
31 | ##$INSTDIR## | ##/opt/fooapp##
32 | ##$JKDIR## | ##/opt/modjk##
33
34 In reality, these directories could be located anywhere.
35
36 == Objective ==
37
38 The objective of this article is to show that a WebObjects application can be deployed into a servlet container and keep some of the desirable attributes of a WebObjects deployment topology. Some of these traits are itemised below.
39
40 * Clustering over a number of hardware nodes to prevent system downtime from a single hardware failure incident.
41 * Clustering over a number of virtual machine //instances// on each hardware node to avoid downtime from a single software failure incident.
42 * Ability to make efficient use of lower cost server hardware rather than encouraging use of large, expensive servers.
43 * Make maximum use of memory availabile in each virtual machine as cache to minimise database traffic and lower stress on the database server.
44 * Ability to make sessions "sticky" to a given virtual machine //instance//, whilst being multiplexed through a single web server front-end adaptor.
45 * Ability to load-balance requests to instances which are operational.
46
47 A standard WebObjects deployment topology is shown in the figure below alongside what is to be achieved with Tomcat. A typical J2EE deployment may have a different topology from this.
48
49 [[image:wo-tomcat-deploy-topology.gif]]
50
51 = Servlet Build Products =
52
53 Creating a servlet build product from a WebObjects application project is covered in some depth by documentation that is supplied by Apple for WebObjects. This is not going to be repeated here, but here is a brief overview of the process.
54
55 * Include the ##JavaWOJSPServlet.framework## framework into your project.
56 * In the build settings, set the ##SERVLET//SINGLE//DIR//DEPLOY//##// value to ##YES## to create the most trouble-free form of deployment servlet.//
57 * Edit the ##SERVLET//DEPLOY//LICENSE## to contain your valid deployment license key if you need one for the version of WebObjects you are using.
58 * Edit the ##SERVLET//WEBAPPS//DIR## to point to ##$INSTDIR/webapps/## or some place where you want the build product to go.
59
60 Now when you choose a //Deployment// build, you will also get the servlet assembled. The end result is a directory structure similar to that shown in the figure below.
61
62 [[image:wo-tomcat-ssd-filelayout-3.gif]]
63
64 = Removing the DOCTYPE from .plist Files =
65
66 Many property-list files (often called plist files) have a document type at the top. This can refer to files on a MacOS-X machine or to files on Apple servers. In either case this can cause problems with deployments which are not on MacOS-X servers. The following script can be run with the argument of the ##WEB-INF## folder to remove these. The WebObjects application runs fine without this information in the plist files. This script can easily be incorporated one way or another as a step in the build process for your WebObjects project.
67
68 {{code}}
69
70 # [apl 3.may.2006]
71 # This will remove any DOCTYPE's from the top of plists so that
72 # they do not attempt to validate the DTD which is either
73 # extracted from /System or the internet over HTTP.
74
75 if [ -z $1 ]; then
76 echo "syntax: stripdocype.sh <directory>"
77 exit 1
78 fi
79
80 for PLISTFILE in `find $1 -name *.plist`
81 do
82 sed \
83 '/<!DOCTYPE [^>]*>/s/.*//' \
84 $PLISTFILE \
85 > /tmp/remove-plist-temp
86
87 cp /tmp/remove-plist-temp $PLISTFILE
88 done
89
90 {{/code}}
91
92 = Application Configuration with Tomcat =
93
94 A WebObjects project with servlet support has a file called ##web.xml.template## in it. By default, this is located in ##/Resources/Servlet Resources/WEB-INF## in your project. The ##web.xml.template## file is used as a template for creating ##web.xml## which is also known as the ##servlet deployment descriptor##. This deployment descriptor is used as the means of communicating settings to the application as well as the servlet container in which the application runs. This section covers some common changes to that file as well as a discussion around a means of general configuration of the application when it is running inside a servlet container.
95
96 == Data Source for Model Database Configuration ==
97
98 Some WebObjects engineers use the ##setConnectionDictionary(...)## method on a model to set the JDBC database connection parameters for the model. However, the servlet container has it's own ##data source## mechanism for supplying database information which will override any connection dictionary information which is set into the model. If you don't want this to happen, and you want your ##setConnectionDictionary(...)## to take effect, comment out the ##resource-ref## item with the title ##jdbc/DefaultDataSource## in the ##web.xml.template## file.
99
100 == Serving WebServerResources ==
101
102 To stop the web server resources (images, CSS files and other static data) from being served out of the java environment, you need to configure the ##context-param## with the name ##WOAppMode## to be ##Deployment## in the ##web.xml.template## file.
103
104 == Application Specific Configuration ==
105
106 This area of configuration covers items such as the following ficticious examples;
107
108 1. Email address of person to contact when system fails.
109 1. Frequency of polling some resource.
110 1. Optional connection information for databases.
111 1. GST rate for New Zealand.
112
113 In other words, these are application-specific configuration values. One way to configure your application specific parameters in a servlet container is to load your config into ##env-entry##s in your ##web.xml## file. Here is such an example of one such entry;
114
115 {{code value="xml"}}
116
117 <env-entry>
118 <env-entry-name>foo/nz.co.foo.FooAppMailFrom</env-entry-name>
119 <env-entry-value>bar@foo.co.nz</env-entry-value>
120 <env-entry-type>java.lang.String</env-entry-type>
121 </env-entry>
122
123 {{/code}}
124
125 You can retrieve these value inside the application with some code as shown below. See the LEConfig class from LEWOStuff, the WebObjects framework from Lindesay Electric for an example. LEWOStuff also comes with a tool to help load standard java properties files into the servlet deployment descriptor.
126
127 {{code}}
128
129 import javax.naming.*;
130
131 // ...later in the same class...
132
133 Object valueO = null;
134
135 try
136 {
137 InitialContext context = new InitialContext();
138 valueO = context.lookup("java:comp/env/foo/nz.co.foo.FooAppMailFrom");
139 }
140 catch(javax.naming.NamingException ne)
141 { /* handle gracefully */ }
142
143 {{/code}}
144
145 It is probably easiest to apply these settings in some automated fashion to the ##web.xml## file as part of a further automated build or deploy process.
146
147 == Application Binary ==
148
149 Put your application servlet build product at ##$INSTDIR## such that the following path exists.
150
151 {{noformat}}
152
153 $INSTDIR/webapps/FooApp/WEB-INF
154
155 {{/noformat}}
156
157 == Tomcat Server Configuration Files ==
158
159 You need to create a tomcat configuration file for each of the instances that you would like to have. The pattern is followed here of having an instance number proceeded by the lower case letter "i". Put the first server configuration file at the following location.
160
161 {{noformat}}
162
163 $INSTDIR/server_i1.xml
164
165 {{/noformat}}
166
167 Here is an example of how this file might look. There is no coverage of the individual settings here as the reader is expected to review the tomcat documentation to discover the specific meanings of these settings.
168
169 === Tomcat 5 ===
170
171 {{code value="xml"}}
172
173 <Server port="7071" shutdown="SHUTDOWN">
174 <Service name="Catalina">
175 <Connector port="8081" maxHttpHeaderSize="8192"
176 maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
177 enableLookups="false" acceptCount="100"
178 connectionTimeout="20000" disableUploadTimeout="true" />
179
180 <Connector port="9091" enableLookups="false" protocol="AJP/1.3" />
181
182 <Engine name="i1" defaultHost="appserver1.foo.co.nz" jvmRoute="i1">
183 <Host name="appserver1.foo.co.nz"
184 appBase="/home/fooapp/webapps"
185 unpackWARs="true" autoDeploy="false"
186 xmlValidation="false" xmlNamespaceAware="false">
187 <Context cookies="false" docBase="FooApp"
188 path="FooApp" reloadable="false">
189 <Manager distributable="false" />
190 </Context>
191 </Host>
192 </Engine>
193
194 </Service>
195 </Server>
196
197 {{/code}}
198
199 === Tomcat 3 ===
200
201 {{code value="xml"}}
202
203 <?xml version="1.0" encoding="ISO-8859-1"?>
204
205 <Server>
206 <ContextManager workDir="work">
207
208 <LoaderInterceptor11 useApplicationLoader="true" />
209
210 <AutoDeploy source="modules" target="modules" redeploy="true" />
211 <AutoWebApp dir="modules" host="DEFAULT" trusted="true"/>
212 <AutoWebApp dir="/home/fooapp/webapps" trusted="true" reloadable="false" />
213
214 <SimpleMapper1 />
215
216 <SessionExpirer checkInterval="60" />
217 <SessionIdGenerator randomClass="java.security.SecureRandom" />
218
219 <WebXmlReader validate="false" />
220 <ErrorHandler showDebugInfo="true" />
221
222 <Jdk12Interceptor />
223 <LoadOnStartupInterceptor />
224 <Servlet22Interceptor />
225
226 <SessionId cookiesFirst="false" noCookies="true" />
227 <SimpleSessionStore maxActiveSessions="256" />
228
229 <Http10Connector port="8081" secure="false" />
230 <Ajp13Connector port="9091" tomcatAuthentication="false" shutdownEnable="true" />
231
232 </ContextManager>
233 </Server>
234
235 {{/code}}
236
237 Assuming that there will be three instances in this example deploy, this entire file should be replicated and modified twice for the other two instances. For the other instances' server configuration files, change the "i1" (Tomcat 5 only) by modifying the numerical component and change the port numbers by making the last digit the instance number. For example, the ports ##7071##, ##8081## and ##9091## are used here. For "i2", use ##7072##, ##8082## and ##9092##.
238
239 You should have three files now present called ##server//i1.xml//##//, ##server##//##i2.xml## and ##server//i3.xml//##// in the directory ##$INSTDIR##.//
240
241 == Startup An Instance ==
242
243 To startup an instance, issue a command as follows. You should issue this command for each of the server configuration files. The ##$JAVA//HOME//##// shell environment variable should have been setup correctly before launching an instance.//
244
245 === Tomcat 5 ===
246
247 {{noformat}}
248
249 $TOMCATDIR/bin/startup.sh -config $INSTDIR/server_i1.xml
250
251 {{/noformat}}
252
253 === Tomcat 3 ===
254
255 {{noformat}}
256
257 $TOMCATDIR/bin/startup -config $INSTDIR/server_i1.xml -home $TOMCATDIR
258
259 {{/noformat}}
260
261 === Tomcat 3 Environment Variables ===
262
263 To pass java environment variables to your application, set the ##TOMCAT//OPTS//##// shell environment variable before starting up the Tomcat 3 environment. An example of this would be as follows;//
264
265 {{noformat}}
266
267 TOMCAT_OPTS=-Dabc=xyz
268 export TOMCAT_OPTS
269
270 {{/noformat}}
271
272 == Check Availability ==
273
274 You can now see if your instance is up using the following URL.
275
276 {{noformat}}
277
278 http://appserver1.foo.co.nz:8081/FooApp/WebObjects/FooApp.woa
279
280 {{/noformat}}
281
282 Note that both the AJP (This is the protocol between the apache adaptor and the individual Tomcat instances.) and the regular HTTP engines are accessing the same running application. This means that a test straight onto the application via HTTP is actually testing the application that is being accessed via AJP. This behaviour provides an opportunity to be able to monitor specific instances of Tomcat over direct HTTP.
283
284 Check each of your instances.
285
286 == Problems ==
287
288 Under Tomcat 5, check the log file at ##$TOMCATHOME/logs/catalina.out## if you are unable to access your instance.
289
290 == Shutdown An Instance ==
291
292 To shutdown an instance, issue a command as follows.
293
294 === Tomcat 5 ===
295
296 {{noformat}}
297
298 $TOMCATDIR/bin/shutdown.sh -config $INSTDIR/server_i1.xml
299
300 {{/noformat}}
301
302 It is also possible to use the UNIX ##telnet## command to connect to the port described in the server configuration file's ##Server## tag and type the word supplied in the ##shutdown## attribute to take out the Tomcat instance.
303
304 === Tomcat 3 ===
305
306 {{noformat}}
307
308 TOMCATDIR/bin/shutdown -ajp13 -port 9091
309
310 {{/noformat}}
311
312 = Apache Adaptor Setup =
313
314 A final deployment usually involves apache feeding inbound requests to instances and handling situations where an instance has gone down and balancing load over the instances that are currently running. This job is undertaken by ##mod//jk//##// which is a module for apache written by the Tomcat group. This module communicates with the tomcat instances using a protocol called ##AJP##. This protocol carries all the information required to check instances are operational as well as relaying requests to the instances. It is assumed that the configuration as well as binaries for the ##mod##//##jk## apache module will be located at ##$JKDIR##.
315
316 == Compiling and Installing ==
317
318 Instructions for downloading and installing ##mod//jk//##// can be obtained from the Tomcat website. The ##mod##//##jk.so## binary should be located at the following path.
319
320 {{noformat}}
321
322 $JKDIR/mod_jk.so
323
324 {{/noformat}}
325
326 Add a line to your system's apache httpd configuration file like this:
327
328 {{noformat}}
329
330 Include /opt/modjk/apache.conf
331
332 {{/noformat}}
333
334 Edit this file to look like this:
335
336 {{noformat}}
337
338 LoadModule jk_module /opt/modjk/mod_jk.so
339 AddModule mod_jk.c
340
341 JkLogFile /opt/modjk/mod_jk.log
342 JkLogLevel info
343
344 JkWorkerProperty worker.list=i1,i2,i3,loadbalancer
345 JkWorkerProperty worker.i1.type=ajp13
346 JkWorkerProperty worker.i1.port=9091
347 JkWorkerProperty worker.i1.host=appserver1.foo.co.nz
348 JkWorkerProperty worker.i1.lbfactor=1
349 JkWorkerProperty worker.i2.type=ajp13
350 JkWorkerProperty worker.i2.port=9092
351 JkWorkerProperty worker.i2.host=appserver1.foo.co.nz
352 JkWorkerProperty worker.i2.lbfactor=1
353 JkWorkerProperty worker.i3.type=ajp13
354 JkWorkerProperty worker.i3.port=9093
355 JkWorkerProperty worker.i3.host=appserver1.foo.co.nz
356 JkWorkerProperty worker.i3.lbfactor=1
357 JkWorkerProperty worker.loadbalancer.type=lb
358 JkWorkerProperty worker.loadbalancer.sticky_session=1
359 JkWorkerProperty worker.loadbalancer.local_worker_only=1
360 JkWorkerProperty worker.loadbalancer.balance_workers=i1,i2,i3
361
362 JkMount /FooApp/* loadbalancer
363
364 {{/noformat}}
365
366 Again, the details of the exact settings will not be covered in this article, but this should provide a simple guide to setting up this file to provide for a multi-instance deploy under Tomcat.
367
368 == Restart Apache ==
369
370 Now restart apache with the following command:
371
372 {{noformat}}
373
374 sudo apachectl restart
375
376 {{/noformat}}
377
378 == Test Application ==
379
380 Now you can test your application using a URL such as this one.
381
382 {{noformat}}
383
384 http://www.foo.co.nz/FooApp/WebObjects/FooApp.woa
385
386 {{/noformat}}
387
388 All three instances that you have setup should take some of the inbound requests.
389
390 == Choosing the Right Instance ==
391
392 ##mod//jk//##// ensures that requests that have started a session will be directed to the correct instance where the session originated. This behaviour is known as sticky sessions. It does not appear to be possible to nominate the instance from the servlet container in another way.//