More detailed installation information:

Read the Quick Installation Notes section in the index.html prior to this document.

Site Content:

• Security settings
• JVM installation and configuration
• Servlet runner configuration
  • Apache's Tomcat (v3.2.x or older)
  • Apache's Tomcat (v4.x, "Catalina")
  • Mortbay's Jetty (v4.x)
  • Remarks to the usage of other servlet runners
• Troubleshooting

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.

• 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.

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.

• 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.

• 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.

• 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).

• 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.