More detailed installation information:
Read the Quick Installation Notes section in the index.html prior to this document.
Site Content:
Security settings:
The user under which your servlet runner is running must have read/write access to the <configdir>
directory. Additionally, read access to each specified provider directory (see parameter values named
"MAILFORMPROVIDER.<provider-name>.PROVIDERDIRECTORY" in the <configdir>/mailwebform.properties)
is needed. If the engine is not able to access those directories, it will fail throwing some I/O or
file-not-found/-accessible exception.
JVM installation and configuration:
- Install a JDK (not only a JRE!) of at least v1.3.1. You may download it from
http://java.sun.com/j2se.
- Set an environment variable named "JAVA_HOME" that points to your JDK installation base directory.
- Add the JAVA_HOME/bin directory to your PATH variable, if you like.
Servlet runner configuration:
Apache's Tomcat (v3.2.x or older):
- Set an environment variable named TOMCAT_HOME that points to your tomcat installation base directory.
- Add the JVM property named
-Dmailwebform.configdir=<configdir>
to the start-up script
(tomcat.bat on Windows, tomcat.sh on Linux/Unix). There is a variable named TOMCAT_OPTS in this script; append
the property to the first occurrence of this variable, separated with a space. A good reference is the handling
of Tomcat's own JVM property named -Dtomcat.home=<TOMCAT_HOME>
.
- Extract the mailwebform.war (which actually is a ZIP file) of the distribution into a directory of your choice
(hence referred to as "MailWebFormInstallDir").
- open the file TOMCAT_HOME/conf/server.xml and add the following tag to the section named "Special webapps":
<Context path="/mailwebform" docBase="MailWebFormInstallDir" debug="0" reloadable="true"></Context>
This path is either relative to the TOMCAT_HOME/webapps directory or absolute, but always a path name, never an URL.
In Windows use either double backslash notation (e.g. c:\\somedir\\anotherdir\\mailwebform) or - preferrably - single
forward slash notation. Save the file.
- If you want to run Tomcat as a service on Windows refer to the
NT service How-to.
Note: In this case you need to edit the wrapper.properties file mentioned in this manual to set the CLASSPATH,
TOMCAT_HOME and JAVA_HOME variables as well as the mailwebform.configdir JVM property.
- Start Tomcat. (Windows Service: Start the service; Windows manual: run TOMCAT_HOME\bin\startup.bat, Unix/Linux:
run TOMCAT_HOME/bin/startup.sh). If everything went well, you can navigate with your browser to
http://localhost:8080.
Try to execute an example servlet and/or JSP site! If this fails, see the Tomcat docs for how to install.
- Now continue with the configuration of the application, as described in the
providersetup.html.
Apache's Tomcat (v4.x, "Catalina")
- Windows NT Service: If you installed Catalina with the installer, it has installed itself as a Windows service and reads
its configuration from the registry. In this case, you need to open the Registry Editor (Start -gt; Run ->
"regedit") and navigate to the key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Apache Tomcat
[version]\Parameters. In the right window, you add a new String value (right mouse click -> New -> String value)
named "JVM Option Number <#>", where # is the next-higher number in the list of the already defined
JVM options. Double-click this new value and type
-Dmailwebform.configdir=<configdir>
into the
text field (you must enter the real path to the config directory, of course). After having done so, add 1 to the
value stored in the entry "JVM Option Count". This will look as follows (added and modified entries are
selected):
Important: If your registry editor doesn't look like this, i.e. contains one single property only that points
to the wrapper.properties, please edit this file directly (see Tomcat above)!
- Unix/Linux/Windows manual installation: Add the JVM property named
-Dmailwebform.configdir=<configdir>
to the start-up script (catalina.bat on Windows, catalina.sh on Linux/Unix). There is a variable named CATALINA_OPTS
at the beginning of this script; append the property to the other ones, separated with a space.
On Unix/Linux, catalina.sh will look as follows:
On Windows, catalina.bat will look as follows:
- Start Catalina. (Windows Service: Start the service; Windows manual: run CATALINA_HOME\bin\startup.bat or
through the start menu, Unix/Linux: run CATALINA_HOME/bin/startup.sh). If everything went well, you can navigate
with your browser to http://localhost:8080.
Try to execute an example servlet and/or JSP site! If this fails, see the Tomcat docs for how to install.
- Open the manager by navigating to http://localhost:8080/manager/html
and log in (default account is admin/manager). On the manager page itself, locate the "Install/Upload a WAR
file to install" section. Navigate to the location of the mailwebform.war file using the "Browse..."
button and hit the "Install" button after having selected the WAR file. On the following page, there will
be a message named "OK - Installed application at context path /mailwebform" at the top of the screen.
- Now continue with the configuration of the application, as described in the
providersetup.html.
Mortbay's Jetty (v4.x)
- Open the jetty.sh file in Jetty's installation directory, subfolder "bin". This script uses the variable
JAVA_OPTIONS, and you must add MailWebForm's <configdir> to the list of the additional JVM properties listed in
there, in exactly the same way as described in the Catalina section above, point "Unix/Linux/Windows manual
installation".
- Copy the mailwebform.war file to Jetty's installation directory, subfolder "webapps".
- Start Jetty be running the jetty.sh script. If everything went well, you can navigate
with your browser to http://localhost:8080.
- Now continue with the configuration of the application, as described in the
providersetup.html.
Remarks to the usage of other servlet runners
- The software works fine with Tomcat, Catalina and Jetty (the same does apply to Catalina and Jetty in the bundle
with the application server JBoss 3.x.
- The mailwebform.war file strictly follows Sun's JSP specification and is installable on any servlet runner that
implements this specification. Please refer to the documentation of your servlet runner for how to install such a
WAR file (Web Application Repository, sometimes also Web ARchive).
Troubleshooting
- In case you see MailWebForm's error message stating that the mailwebform.configdir property isn't defined, open
the systemproperties.jsp in your browser (e.g.
http://localhost:8080/mailwebform/systemproperties.jsp).
This file lists all of the registered JVM properties and allows you to verify whether your configuration was successful.
- On some servlet runners, you see an error message stating that the javax.servlet.Servlet class of the mailwebform.war
isn't loaded since it conflicts with the servlet runner's own version of this class. Ignore this message as long as
you're sure that your servlet runner implements the JSP specification 2.2 or higher. To get rid of it, open the
mailwebform.war and remove the javax.servlet.jar file from the WEB-INF/lib directory.
- If you're running more than one servlet runner on your server/host, they'll probably conflict with each other since
they're all using the ports 8080 (web connection) and 8009 (shutdown). In this case, you'll need to change the
configuration of your servlet runners (Tomcat/Catalina: conf/server.xml, Jetty: jetty.sh). Locate those port numbers
and modify them, e.g. use 8181 and 8109 instead of 8080 and 8009. Restart the servlet runner after these modifications.