Wiki source code of Deploying with Tomcat

Last modified by Pascal Robert on 2010/11/30 05:54

Manage
- Copy
Actions
Viewers
- Source
- Children
- Content
- Comments
- Attachments (2)
- History
- Information
- Likes

version	line-number	content
19.1	1	This article was written by Andrew Lindesay ([[http:~~/~~/www.lindesay.co.nz>>url:http://www.lindesay.co.nz\|\|shape="rect"]]) 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.
3.1	2
21.1	3	More information on tomcat deployment using Eclipse/WOLips, including information on how to deploy Project Wonder applications, is available [[here>>doc:WO.Home.Deprecated.Creating a wonder app to deploy as a servlet.WebHome]]
16.1	4
19.1	5	\|=(((
	6	Contents
	7	)))
	8	\|(((
	9	{{toc style="disc"/}}
	10	)))
13.1	11
8.1	12	= Abstract =
	13
	14	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
19.1	15	deploy a WebObjects 5.2 application into a Tomcat environment and achieve a very similar topology to the "native" WebObjects deploy.
3.1	16
8.1	17	= Introduction =
3.1	18
8.1	19	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.
3.1	20
8.1	21	= Assumptions =
3.1	22
	23	This article assumes the following:
	24
	25	* WebObjects 5.2 (likely to work fine with newer versions)
	26	* Java 1.4
	27	* Latest Tomcat release of version 5 (5.5.12 at the time of writing) or 3 (3.3.2 at the time of writing)
	28	* Some sort of UNIX deployment.
	29	* The reader has some conception of the concepts behind servlet technology.
	30	* The reader is familiar with a standard WebObjects deployment topology which will be referred to as //wotaskd// deployment.
	31
19.1	32	For the purposes of this document, it is assumed that Tomcat has been installed at a directory on the local disc called {{code language="none"}}$TOMCATDIR{{/code}}. It is also assumed that you will have another directory with the files required to configure and run an instance called {{code language="none"}}$INSTDIR{{/code}}. It is assumed also that you will have a directory called {{code language="none"}}$JKDIR{{/code}} with the Tomcat apache adaptor in it. In this article, some configuration files require the paths to be shown and these are tabulated below.
3.1	33
19.1	34	\|(((
21.1	35	{{code language="none"}}
	36	$TOMCATDIR
	37	{{/code}}
19.1	38	)))\|(((
21.1	39	{{code language="none"}}
	40	/opt/tomcat
	41	{{/code}}
19.1	42	)))
	43	\|(((
21.1	44	{{code language="none"}}
	45	$INSTDIR
	46	{{/code}}
19.1	47	)))\|(((
21.1	48	{{code language="none"}}
	49	/opt/fooapp
	50	{{/code}}
19.1	51	)))
	52	\|(((
21.1	53	{{code language="none"}}
	54	$JKDIR
	55	{{/code}}
19.1	56	)))\|(((
21.1	57	{{code language="none"}}
	58	/opt/modjk
	59	{{/code}}
19.1	60	)))
	61
3.1	62	In reality, these directories could be located anywhere.
	63
8.1	64	== Objective ==
3.1	65
19.1	66	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.
3.1	67
	68	* Clustering over a number of hardware nodes to prevent system downtime from a single hardware failure incident.
	69	* Clustering over a number of virtual machine //instances// on each hardware node to avoid downtime from a single software failure incident.
	70	* Ability to make efficient use of lower cost server hardware rather than encouraging use of large, expensive servers.
	71	* Make maximum use of memory availabile in each virtual machine as cache to minimise database traffic and lower stress on the database server.
	72	* Ability to make sessions "sticky" to a given virtual machine //instance//, whilst being multiplexed through a single web server front-end adaptor.
	73	* Ability to load-balance requests to instances which are operational.
	74
19.1	75	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.
3.1	76
19.1	77	[[image:attach:wo-tomcat-deploy-topology.gif]]
3.1	78
8.1	79	= Servlet Build Products =
3.1	80
19.1	81	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.
3.1	82
19.1	83	* Include the {{code language="none"}}JavaWOJSPServlet.framework{{/code}} framework into your project.
	84	* In the build settings, set the {{code language="none"}}SERVLET_SINGLE_DIR_DEPLOY{{/code}} value to {{code language="none"}}YES{{/code}} to create the most trouble-free form of deployment servlet.
	85	* Edit the {{code language="none"}}SERVLET_DEPLOY_LICENSE{{/code}} to contain your valid deployment license key if you need one for the version of WebObjects you are using.
	86	* Edit the {{code language="none"}}SERVLET_WEBAPPS_DIR{{/code}} to point to {{code language="none"}}$INSTDIR/webapps/{{/code}} or some place where you want the build product to go.
3.1	87
19.1	88	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.
3.1	89
19.1	90	[[image:attach:wo-tomcat-ssd-filelayout-3.gif]]
3.1	91
8.1	92	= Removing the DOCTYPE from .plist Files =
3.1	93
19.1	94	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 {{code language="none"}}WEB-INF{{/code}} 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.
3.1	95
	96	{{code}}
	97
	98	# [apl 3.may.2006]
	99	# This will remove any DOCTYPE's from the top of plists so that
	100	# they do not attempt to validate the DTD which is either
	101	# extracted from /System or the internet over HTTP.
	102
	103	if [ -z $1 ]; then
	104	echo "syntax: stripdocype.sh <directory>"
	105	exit 1
	106	fi
	107
	108	for PLISTFILE in `find $1 -name *.plist`
	109	do
	110	sed \
18.1	111	'/<!DOCTYPE [Deploying with Tomcat^>]>/s/.//' \
3.1	112	$PLISTFILE \
	113	> /tmp/remove-plist-temp
	114
	115	cp /tmp/remove-plist-temp $PLISTFILE
	116	done
	117
	118	{{/code}}
	119
8.1	120	= Application Configuration with Tomcat =
3.1	121
19.1	122	A WebObjects project with servlet support has a file called {{code language="none"}}web.xml.template{{/code}} in it. By default, this is located in {{code language="none"}}/Resources/Servlet Resources/WEB-INF{{/code}} in your project. The {{code language="none"}}web.xml.template{{/code}} file is used as a template for creating {{code language="none"}}web.xml{{/code}} which is also known as the {{code language="none"}}servlet deployment descriptor{{/code}}. 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.
3.1	123
8.1	124	== Data Source for Model Database Configuration ==
3.1	125
19.1	126	Some WebObjects engineers use the {{code language="none"}}setConnectionDictionary(...){{/code}} method on a model to set the JDBC database connection parameters for the model. However, the servlet container has it's own {{code language="none"}}data source{{/code}} 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 {{code language="none"}}setConnectionDictionary(...){{/code}} to take effect, comment out the {{code language="none"}}resource-ref{{/code}} item with the title {{code language="none"}}jdbc/DefaultDataSource{{/code}} in the {{code language="none"}}web.xml.template{{/code}} file.
3.1	127
16.1	128	If you have more than one data source Resource defined in either your WEB-INF/web.xml or in your META-INF/Context.xml file, WebObjects will complain about there being more than one configuration with this error:
	129
19.1	130	{{code language="none"}}An exception occurred while trying to open a channel: com.webobjects.jdbcadaptor.JDBCAdaptorException: Found multiple data sources. Please map the EOModels to a data source explicitly!{{/code}}
16.1	131
	132	You must set the name parameter of each data source Resource in the web.xml/Context.xml with the same name as your eomodel file. For example:
	133
	134	EOModel name: MyModel.eomodel
	135
	136	data source Resource definition:
	137
	138	{{code}}
	139
	140	<Resource
	141	auth="Container"
	142	description="MyApp Data Source"
	143	HERE -> name="MyModel"
	144	type="javax.sql.DataSource"
	145	driverClassName="com.microsoft.jdbc.sqlserver.SQLServerDriver"
	146	url="jdbc:microsoft:sqlserver://serveraddress:1433;databaseName=TEST"
	147	username="user"
	148	password="pass"
	149	maxActive="4"
	150	maxWait="5000"
	151	maxIdle="10"
	152	/>
	153
	154	{{/code}}
	155
8.1	156	== Serving WebServerResources ==
3.1	157
19.1	158	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 {{code language="none"}}context-param{{/code}} with the name {{code language="none"}}WOAppMode{{/code}} to be {{code language="none"}}Deployment{{/code}} in the {{code language="none"}}web.xml.template{{/code}} file.
3.1	159
8.1	160	== Application Specific Configuration ==
3.1	161
	162	This area of configuration covers items such as the following ficticious examples;
	163
	164	1. Email address of person to contact when system fails.
	165	1. Frequency of polling some resource.
	166	1. Optional connection information for databases.
	167	1. GST rate for New Zealand.
	168
19.1	169	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 {{code language="none"}}env-entry{{/code}}-s in your {{code language="none"}}web.xml{{/code}} file. Here is such an example of one such entry;
3.1	170
19.1	171	{{code 0="xml"}}
3.1	172
	173	<env-entry>
13.1	174	<env-entry-name>foo/nz.co.foo.FooAppMailFrom</env-entry-name>
	175	<env-entry-value>bar@foo.co.nz</env-entry-value>
	176	<env-entry-type>java.lang.String</env-entry-type>
3.1	177	</env-entry>
	178
	179	{{/code}}
	180
19.1	181	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.
3.1	182
	183	{{code}}
	184
	185	import javax.naming.*;
	186
	187	// ...later in the same class...
	188
	189	Object valueO = null;
8.1	190
3.1	191	try
	192	{
	193	InitialContext context = new InitialContext();
	194	valueO = context.lookup("java:comp/env/foo/nz.co.foo.FooAppMailFrom");
	195	}
	196	catch(javax.naming.NamingException ne)
	197	{ /* handle gracefully */ }
	198
	199	{{/code}}
	200
19.1	201	It is probably easiest to apply these settings in some automated fashion to the {{code language="none"}}web.xml{{/code}} file as part of a further automated build or deploy process.
3.1	202
8.1	203	== Application Binary ==
3.1	204
19.1	205	Put your application servlet build product at {{code language="none"}}$INSTDIR{{/code}} such that the following path exists.
3.1	206
10.1	207	{{noformat}}
3.1	208
	209	$INSTDIR/webapps/FooApp/WEB-INF
	210
10.1	211	{{/noformat}}
3.1	212
8.1	213	== Tomcat Server Configuration Files ==
3.1	214
19.1	215	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.
3.1	216
10.1	217	{{noformat}}
3.1	218
	219	$INSTDIR/server_i1.xml
	220
10.1	221	{{/noformat}}
3.1	222
19.1	223	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.
3.1	224
8.1	225	=== Tomcat 5 ===
3.1	226
19.1	227	{{code 0="xml"}}
3.1	228
	229	<Server port="7071" shutdown="SHUTDOWN">
	230	<Service name="Catalina">
	231	<Connector port="8081" maxHttpHeaderSize="8192"
	232	maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
	233	enableLookups="false" acceptCount="100"
	234	connectionTimeout="20000" disableUploadTimeout="true" />
	235
	236	<Connector port="9091" enableLookups="false" protocol="AJP/1.3" />
	237
	238	<Engine name="i1" defaultHost="appserver1.foo.co.nz" jvmRoute="i1">
	239	<Host name="appserver1.foo.co.nz"
	240	appBase="/home/fooapp/webapps"
	241	unpackWARs="true" autoDeploy="false"
	242	xmlValidation="false" xmlNamespaceAware="false">
	243	<Context cookies="false" docBase="FooApp"
	244	path="FooApp" reloadable="false">
	245	<Manager distributable="false" />
	246	</Context>
	247	</Host>
8.1	248	</Engine>
3.1	249
	250	</Service>
	251	</Server>
	252
	253	{{/code}}
	254
8.1	255	=== Tomcat 3 ===
3.1	256
19.1	257	{{code 0="xml"}}
3.1	258
	259	<?xml version="1.0" encoding="ISO-8859-1"?>
	260	<Server>
13.1	261	<ContextManager workDir="work">
	262	<LoaderInterceptor11 useApplicationLoader="true"/>
3.1	263
13.1	264	<AutoDeploy source="modules" target="modules" redeploy="true"/>
	265	<AutoWebApp dir="modules" host="DEFAULT" trusted="true"/>
	266	<AutoWebApp dir="/home/fooapp/webapps" trusted="true" reloadable="false"/>
3.1	267
13.1	268	<SimpleMapper1/>
3.1	269
13.1	270	<SessionExpirer checkInterval="60"/>
	271	<SessionIdGenerator randomClass="java.security.SecureRandom"/>
3.1	272
13.1	273	<WebXmlReader validate="false"/>
	274	<ErrorHandler showDebugInfo="true"/>
3.1	275
13.1	276	<Jdk12Interceptor/>
	277	<LoadOnStartupInterceptor/>
	278	<Servlet22Interceptor/>
3.1	279
13.1	280	<SessionId cookiesFirst="false" noCookies="true"/>
	281	<SimpleSessionStore maxActiveSessions="256"/>
3.1	282
13.1	283	<Http10Connector port="8081" secure="false"/>
	284	<Ajp13Connector port="9091" tomcatAuthentication="false" shutdownEnable="true"/>
	285	</ContextManager>
3.1	286	</Server>
	287
	288	{{/code}}
	289
19.1	290	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 {{code language="none"}}7071{{/code}}, {{code language="none"}}8081{{/code}} and {{code language="none"}}9091{{/code}} are used here. For "i2", use {{code language="none"}}7072{{/code}}, {{code language="none"}}8082{{/code}} and {{code language="none"}}9092{{/code}}.
3.1	291
19.1	292	You should have three files now present called {{code language="none"}}server_i1.xml{{/code}}, {{code language="none"}}server_i2.xml{{/code}} and {{code language="none"}}server_i3.xml{{/code}} in the directory {{code language="none"}}$INSTDIR{{/code}}.
3.1	293
8.1	294	== Startup An Instance ==
3.1	295
19.1	296	To startup an instance, issue a command as follows. You should issue this command for each of the server configuration files. The {{code language="none"}}$JAVA_HOME{{/code}} shell environment variable should have been setup correctly before launching an instance.
3.1	297
19.1	298	\|=(((
	299	Tomcat 5
	300	)))\|(((
21.1	301	{{code language="none"}}
	302	$TOMCATDIR/bin/startup.sh -config $INSTDIR/server_i1.xml
	303	{{/code}}
19.1	304	)))
	305	\|=(((
	306	Tomcat 3
	307	)))\|(((
21.1	308	{{code language="none"}}
	309	$TOMCATDIR/bin/startup -config $INSTDIR/server_i1.xml -home $TOMCATDIR
	310	{{/code}}
19.1	311	)))
3.1	312
8.1	313	=== Tomcat 3 Environment Variables ===
3.1	314
19.1	315	To pass java environment variables to your application, set the {{code language="none"}}TOMCAT_OPTS{{/code}} shell environment variable before starting up the Tomcat 3 environment. An example of this would be as follows;
3.1	316
10.1	317	{{noformat}}
3.1	318
	319	TOMCAT_OPTS=-Dabc=xyz
	320	export TOMCAT_OPTS
	321
10.1	322	{{/noformat}}
3.1	323
8.1	324	== Check Availability ==
3.1	325
	326	You can now see if your instance is up using the following URL.
	327
10.1	328	{{noformat}}
3.1	329
	330	http://appserver1.foo.co.nz:8081/FooApp/WebObjects/FooApp.woa
	331
10.1	332	{{/noformat}}
3.1	333
19.1	334	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.
3.1	335
	336	Check each of your instances.
	337
8.1	338	== Problems ==
3.1	339
19.1	340	Under Tomcat 5, check the log file at {{code language="none"}}$TOMCATHOME/logs/catalina.out{{/code}} if you are unable to access your instance.
3.1	341
8.1	342	== Shutdown An Instance ==
3.1	343
	344	To shutdown an instance, issue a command as follows.
	345
8.1	346	=== Tomcat 5 ===
3.1	347
10.1	348	{{noformat}}
3.1	349
	350	$TOMCATDIR/bin/shutdown.sh -config $INSTDIR/server_i1.xml
	351
10.1	352	{{/noformat}}
3.1	353
19.1	354	It is also possible to use the UNIX {{code language="none"}}telnet{{/code}} command to connect to the port described in the server configuration file's {{code language="none"}}Server{{/code}} tag and type the word supplied in the {{code language="none"}}shutdown{{/code}} attribute to take out the Tomcat instance.
3.1	355
8.1	356	=== Tomcat 3 ===
3.1	357
10.1	358	{{noformat}}
3.1	359
	360	TOMCATDIR/bin/shutdown -ajp13 -port 9091
	361
10.1	362	{{/noformat}}
3.1	363
8.1	364	= Apache Adaptor Setup =
3.1	365
19.1	366	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 {{code language="none"}}mod_jk{{/code}} which is a module for apache written by the Tomcat group. This module communicates with the tomcat instances using a protocol called {{code language="none"}}AJP{{/code}}. 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 {{code language="none"}}mod_jk{{/code}} apache module will be located at {{code language="none"}}$JKDIR{{/code}}.
3.1	367
8.1	368	== Compiling and Installing ==
3.1	369
19.1	370	Instructions for downloading and installing {{code language="none"}}mod_jk{{/code}} can be obtained from the Tomcat website. The {{code language="none"}}mod_jk.so{{/code}} binary should be located at the following path.
3.1	371
10.1	372	{{noformat}}
3.1	373
	374	$JKDIR/mod_jk.so
	375
10.1	376	{{/noformat}}
3.1	377
	378	Add a line to your system's apache httpd configuration file like this:
	379
10.1	380	{{noformat}}
3.1	381
	382	Include /opt/modjk/apache.conf
	383
10.1	384	{{/noformat}}
3.1	385
	386	Edit this file to look like this:
	387
10.1	388	{{noformat}}
3.1	389
	390	LoadModule jk_module /opt/modjk/mod_jk.so
	391	AddModule mod_jk.c
	392
	393	JkLogFile /opt/modjk/mod_jk.log
	394	JkLogLevel info
	395
	396	JkWorkerProperty worker.list=i1,i2,i3,loadbalancer
	397	JkWorkerProperty worker.i1.type=ajp13
	398	JkWorkerProperty worker.i1.port=9091
	399	JkWorkerProperty worker.i1.host=appserver1.foo.co.nz
	400	JkWorkerProperty worker.i1.lbfactor=1
	401	JkWorkerProperty worker.i2.type=ajp13
	402	JkWorkerProperty worker.i2.port=9092
	403	JkWorkerProperty worker.i2.host=appserver1.foo.co.nz
	404	JkWorkerProperty worker.i2.lbfactor=1
	405	JkWorkerProperty worker.i3.type=ajp13
	406	JkWorkerProperty worker.i3.port=9093
	407	JkWorkerProperty worker.i3.host=appserver1.foo.co.nz
	408	JkWorkerProperty worker.i3.lbfactor=1
	409	JkWorkerProperty worker.loadbalancer.type=lb
	410	JkWorkerProperty worker.loadbalancer.sticky_session=1
	411	JkWorkerProperty worker.loadbalancer.local_worker_only=1
	412	JkWorkerProperty worker.loadbalancer.balance_workers=i1,i2,i3
	413
	414	JkMount /FooApp/* loadbalancer
	415
10.1	416	{{/noformat}}
3.1	417
	418	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.
	419
8.1	420	== Restart Apache ==
3.1	421
	422	Now restart apache with the following command:
	423
10.1	424	{{noformat}}
3.1	425
	426	sudo apachectl restart
	427
10.1	428	{{/noformat}}
3.1	429
8.1	430	== Test Application ==
3.1	431
	432	Now you can test your application using a URL such as this one.
	433
10.1	434	{{noformat}}
3.1	435
	436	http://www.foo.co.nz/FooApp/WebObjects/FooApp.woa
	437
10.1	438	{{/noformat}}
3.1	439
	440	All three instances that you have setup should take some of the inbound requests.
	441
8.1	442	== Choosing the Right Instance ==
3.1	443
19.1	444	{{code language="none"}}mod_jk{{/code}} 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.

Wiki source code of Deploying with Tomcat

Applications

Navigation

My Recent Modifications

Need help?