blob: b01b1be3392883cff8be4d34c7b82f5524074ed4 [file] [log] [blame]
$Id: INSTALL,v 2001/07/21 06:18:33 martinc Exp $
This document contains notes that have been accumulated on getting the Struts
applications (documentation and example) running in a variety of servlet
container environments.
For most containers, you need only to:
* Copy the WAR files in your Struts < /webapp > directory to your containers
< webapps > directory.
* In some cases, you may need to restart your container if it is running.
Status of various containers -- as reported by volunteers on the Struts-User list.
* Tomcat 3.1+ Standalone - No additonal steps required.
* Resin 1.2+ Standalone - No additional steps required.
* WebLogic 6.0+ - No additional steps required.
* Bluestone Universal Business Server - Additional steps provided below.
* JRUN - Additional steps provided below.
* Orion Application Server - Additional steps provided below.
* Tomcat 3.1+ with Apache - Additional steps provided below.
* Weblogic 5.1 (sp8) - Additional steps provided below.
* Websphere - Determination pending.
* You need UBS version 7.2 to run war file applications. The UBS 7.2.2
evaluation is located here:
* If you're using version 7.2.1, you need to download the WAR file patch,
located in the product enhancement section of Bluestone's website:
* After installation of the correct version and/or patch of UBS 7.2, you
need to modify your apserver.txt file to point to the correct directory
for your war file applications. Look for the section that says something
similar to the following:
* Use the directory specified by the "file_path" variable, or modify it
to point to your own custom webapp directory. Copy the
"struts-documention.war" and "struts-example.war" files into that
webapp directory, and start the UBS (read documentation distributed
with UBS for information on how to start it if necessary). Your webapps
are now accessible from the following URL's:
* "<PLUGIN>" represents the plugin you are using for your specific
webserver. For apache on Windows, it might be "cgi-bin/SaCGI.exe",
for IIS on Windows, it might be "scripts/SaCGI.exe" or "scripts/ISAPI.dll".
Consult the UBS documentation for more information.
JRUN 3.0 SP2A, VERSION 3.02A.11614
Tested with: Microsoft IIS 5.0, Windows 2000
Important Note:
At the moment, JRun is not fully compliant with the JSP 1.1/1.2
Specifically, the automatic type conversions for custom tag parameters
specified in "Issue 7" of the JSP 1.1 Errata and in the JSP 1.2 Proposed
Final Draft have not yet been implemented.
As it stands, JSP pages that make use of Struts taglibs whose parameters
require conversion (such as booleans) will not compile under JRun. This
includes the Struts Example Application. Attempting to run the example
application will result in an exception similar to the following being
javax.servlet.ServletException: Compilation error occured:
Errors reported by compiler:
c:/JRun/servers/default/Struts Example/WEB-INF/jsp/
Error: No match was found for method "setLocale(java.lang.String)".
(For more details refer to:
< >)
The following instructions describe how to install the Struts Example
Application under JRun. A subsequent section describes how the Struts Example
Application can be patched to work with Struts
The following instructions assume the following:
* JRun has been installed and integrated with the web server of choice
* $APP_SERVER_NAME is the name of the application server used to host the
application. (When JRun is first installed, it creates an application
server called JRun Default Server)
* $APP_SERVER_DIR is the directory used to hold applications hosted by
$APP_SERVER_NAME. For the JRun Default Server, the directory is
$JRUN_HOME/servers/default where $JRUN_HOME is the directory where
JRun is installed.
Installing The Struts Example Application
* Login to the JRun Management Console.
* On the left pane, select $APP_SERVER_NAME. A page showing the
current server status will be shown on the right pane.
* On the right pane, click on the WAR Deployment link. A page
containing a list of the currently deployed web applications will be
* On the right pane, click on Deploy an Application. Complete the Web
Application Information form as follows:
o Servlet War File or Directory: Enter the full path where
struts-example.war is found or click on Browse to select
the path.
o JRun Server Name: $APP_SERVER_NAME
o Application Name: Struts Example
o Application Hosts: All Hosts
o Application URL: /struts-example
o Application Deploy Directory: will default to
$APP_SERVER_NAME/Struts Example (or the name as specified for
Application Name)
* Once the form is complete, click on the Deploy button.
* If deployment is successful, restart the application server by
clicking on $APP_SERVER_NAME on the left pane. A page showing the
current server status will be shown on the right pane. Click the
Restart Server button to restart the application server.
* Test the sample application by using the following URL in the
The struts-documentation.war can be installed using the same
Installing Unpacked Web Applications
The above steps should be followed for applications deployed as *.war files.
For unpacked web applications, configuration involves the following steps:
* From the JRun Management Console, select $APP_SERVER_NAME (on the
left pane) and click on WAR Deployment (on the right pane)
* On the right pane, click on Create an Application and complete the
Web Application Information form as follows:
* JRun Server Name: $APP_SERVER_NAME
o Application Name: myApplication
o Application Hosts: All Hosts
o Application URL: /myApplication
o Application Deploy Directory: will default to
* Click on Create to submit the form.
* Once the web application is created, install and configure the struts
components (struts.jar, struts*.tld, etc) for the web application under
* Install the remaining components of the application: .class files,
JSP pages,.properties files etc as required.
* To configure the extension mapping of the request URI (ie *.do) to
the action servlet, expand $APP_SERVER_NAME on the left pane, expand
the Web Applications branch and click on myApplication. The right pane
will display the configuration options for myApplication. Click on
Servlet URL Mappings. A list of existing mappings will be shown. Click
the Edit button and create the following entry:
o Virtual Path/Extension: *.do
o Servlet Invoked: action
* Click on the Update button to save the changes.
* Restart the application server.
* The application should now be accessible from the browser.
The JRun application server will need to be restarted each time one of the
following changes are made to the web application:
* .class or .jar files are modified
* .properties files are modified
* .xml files are modified
Patching The Struts Example Application
As mentioned at the beginning of these notes, the Struts Example Application
will not run under JRun without modification. The following changes will need
to be made:
* index.jsp, logon.jsp: Change <html:html locale="true"> to
<html:html locale=<%= true %>>
* registration.jsp, subscription.jsp: Change all instances of
filter="true" to filter=<%= true %>
* In the steps below, $ORION_HOME refers to the directory in which you
have installed Orion, and $STRUTS_HOME is the directory in which you
unpacked the Struts binary distribution.
* Modify the file "$ORION_HOME/config/application.xml" to define the two
new applications, by adding the following declarations, immediately
following the <web-module> directive for the default web application:
<web-module id="strutsDoc"
<web-module id="strutsExample"
* Modify the file "$ORION_HOME/config/default-web-site.xml" (or the
configuration file for any other Orion web site) to include the following
declarations, after the declaration for the <default-web-app> if any:
<web-app application="default" name="strutsDoc"
<web-app application="default" name="strutsExample"
* After you start Orion, you should now be able to access these applications
(assuming you haven't changed the port number from the default of 80) at:
* Versions of Orion up to at least 1.0.3 have a bug related to
ServletContext.getResource() calls that prevent the Struts example
application from working out of the box. This manifests itself as a
JSP error when you try to access the example application, with the
following message:
javax.servlet.jsp.JspException: Missing resources attribute
followed by an error traceback. There will also be an initialization
error message in the "$ORION_HOME/log/global-application.log" log file.
To work around this problem, you can take the following steps:
- Go to the "$STRUTS_HOME/webapps" directory, where you will note that
Orion has automatically expanded each web application into an
unpacked directory structure.
- Go to the "$STRUTS_HOME/webapps/struts-example/WEB-INF" directory,
and copy the file "struts-config.xml" one directory up (that is, into
- Modify the "$STRUTS_HOME/webapps/struts-example/WEB-INF/web.xml" file,
changing the value of the "config" initialization parameter (for the
action servlet) from "/WEB-INF/struts-config.xml" to "/struts-config.xml".
- Restart Orion, and you should be able to access the example application.
Note that this workaround has a negative security-related side effect:
your "struts-config.xml" file can now be retrieved by remote clients at the
following URL:
Therefore, you should be sure you do not store sensitive information
(such as database passwords) in this file.
Start the SilverStream application server.
Create an XML deployment plan for the "struts-example.war" application.
Call the file "struts-example-depl-plan.xml". You can use the following
contents for the file
----- cut here -----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE warJarOptions PUBLIC
"-//SilverStream Software, Inc.//DTD J2EE WAR Deployment Plan//EN"
----- cut here -----
Create an XML deployment plan for the "struts-documentation.war"
Call the file "struts-documentation-depl-plan.xml". You can use the
following contents for the file:
----- cut here -----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE warJarOptions PUBLIC
"-//SilverStream Software, Inc.//DTD J2EE WAR Deployment Plan//EN"
----- cut here -----
Run the following "SilverCmd DeployWAR" commands to deploy the applications.
You can change 'localhost' to whatever server you are deploying to. You can
change 'Silvermaster' to whatever database you are deploying to.
SilverCmd DeployWar localhost Silvermaster struts-example.war
-f struts-example-depl-plan.xml
SilverCmd DeployWar localhost Silvermaster struts-documentation.war
-f struts-documentation-depl-plan.xml
* These instructions assume you have successfully integrated
Tomcat with Apache according to the Tomcat documentation.
* Copy "struts-documentation.war" and "struts-example.war"
to your $TOMCAT_HOME/webapps directory
* Restart Tomcat if it is already running
* Tomcat will generate a file "$TOMCAT_HOME/conf/tomcat-apache.conf"
that will be used by Apache. This file is regenerated every time
you start Tomcat, so copy this file to a safe place (such as
your Apache configuration directory; on Unix systems this is usually
* If you are running Tomcat 3.1, Tomcat will not have generated the
entries for your new applications. Add the following lines to the
"tomcat-apache.conf" file that you have saved, replacing
$TOMCAT_HOME with the path to your Tomcat home directory:
Alias /struts-documentation "$TOMCAT_HOME/webapps/struts-documentation"
<Directory "$TOMCAT_HOME/webapps/struts-documentation>
Options Indexes FollowSymLinks
ApJServMount /struts-documentation/servlet /struts-documentation
<Location "/struts-documentation/WEB-INF/">
AllowOverride None
deny from all
Alias /struts-example "$TOMCAT_HOME/webapps/struts-example"
<Directory "$TOMCAT_HOME/webapps/struts-example>
Options Indexes FollowSymLinks
ApJServMount /struts-example/servlet /struts-example
<Location "/struts-example/WEB-INF/">
AllowOverride None
deny from all
* On all versions of Tomcat, the generated file above does not
know anything about extension mappings defined in a web.xml file,
so the "*.do" URIs that go to the controller servlet will not be
recognized. To fix this, add the following line to the saved
version of "tomcat-apache.conf", after the corresponding line
for the .jsp extension:
AddHandler jserv-servlet .do
* Ensure that the saved version of "tomcat-apache.conf" is referenced
in your Apache "httpd.conf" configuration file. A typical use would
have the following line at the bottom of "httpd.conf":
Include /usr/local/apache/conf/tomcat-apache.conf
* In order to recognize "index.jsp" as a default page for web
applications, search in your "httpd.conf" for a "DirectoryIndex"
directive. If you have one, add "index.jsp" to the end of the
list, so that it might look like this:
DirectoryIndex index.html index.jsp
If you do not have such an entry, add one like this:
DirectoryIndex index.jsp
* Restart Apache to make it aware of the new applications. You should
now be able to access the applications from a browser like this:
WEBLOGIC 5.1 (service pack 8)
* Obtain and install the Xerces XML parser (problems have been reported
with the Sun reference implementation). Put xerces.jar in your WebLogic system
* Obtain and unpack the Struts binary distribution (this procedure assumes
it was extracted to C:\jakarta-struts).
* Add an entry to for each of the Struts web
applications that you would like to configure. For example, to make the
struts-example application available, add the following line to
* You do not need to include struts.jar or any of the application specific
classes in the WebLogic classpath, since this will be done automatically
(unless deploying an unpacked web archive- see below).
* Start WebLogic server and point your web browser to the struts
application. For example, to connect to the example application added in
step 3:
* This example application depends on the Struts specific resource file to be present on the classpath. However,
WebLogic only extracts *.class files from the archive so this file will not
be found, resulting in an error the first time it is needed- something
similar to: javax.servlet.ServletException: runtime failure in custom tag
'message'. Steps 6 & 7 will need to be performed for this application, and
any other that relies on
* Extract from the *.war file, and
manually copy it to the respective package in the _tmp_war_ directory
WebLogic created for this application. Again referring to the struts-example
application, this would be:
* Restart WebLogic. You will now be able to run the application:
* The above steps should be followed for applications deployed as *.war
files. For unpacked web applications, configuration involves adding both
struts.jar and /WEB-INF/classes to the WebLogic classpath. For this reason,
I would suggest deploying applications as war files to WebLogic. However,
the same example application can be successfully deployed in extracted
format by modifying (assuming the war was extracted to
directory webapps/struts-example):
And starting WebLogic with the updated WebLogic classpath. For example:
c:\jdk1.3\bin\java -ms16m -mx64m
-classpath c:\weblogic\lib\weblogic510sp8boot.jar;
c:\xerces\xerces.jar -Dweblogic.class.path=c:\weblogic\lib\weblogic510sp8.jar;