Optional Further Configuring

There are a number of additional features that can be obtained by optional extra installation steps. It is not necessary to carry them out to run your webMathematica server, but they are included in this section to provide extra information.

MSP Mathematica Application

The MSP Mathematica application contains useful functions for formatting Mathematica expressions into HTML tables and select tags, in addition to utilities useful for using SVG. It is already installed in the webMathematica layout so that webMathematica will operate without any extra steps. You may wish to use these functions within Mathematica, as when trying examples from the function reference documentation. In order to do this, you will need to configure the $Path variable. This installation step is optional because it is not needed for webMathematica to run.

First, you need to identify where you installed the webMathematica web application. If you are using the Tomcat servlet container, this will be in the webapps subdirectory of Tomcat, so you could set a variable to this directory:

If you are using the Glassfish servlet container, and have installed webMathematica by placing webMathematica.war file in the autodeploy directory, the deployed web application will be in the glassfish/domains/domain1/applications directory (unless you have configured things differently):

Other servlet containers will have different locations to install the web application, you can set the $webappsDir to the directory containing the webMathematica directory.

The next step is to identify the location of the MSP application within the webMathematica folder:

You can verify that this directory is correct by listing its contents and looking for the MSP directory:

Finally, place this directory at the beginning of the application search path. You can then confirm everything is configured by looking for the MSP application:

Viewing webMathematica Documentation in the Mathematica Documentation Center

You may wish to view this webMathematica documentation in the Mathematica Documentation Center. In order to do this, you will need to install the documentation. This installation step is optional. Note that you can also find the documentation on the Wolfram Research web site at http://reference.wolfram.com/mathematica/webMathematica/tutorial/Overview.html.

The webMathematica documentation is in archive form on the webMathematica Tools CD-ROM. Browse to the Extras folder and unpack the file webMathematicaDocumentation.zip into the AddOns/Applications directory in your Mathematica directory. If you do not have permission to write to this directory, you may place it in the Applications subdirectory of $UserBaseDirectory. It should then be possible to launch Mathematica and the webMathematica documentation to appear in the Documentation Center under Add-Ons and Packages or by entering webMathematica/tutorial/Overview into the search input field.

Launching webMathematica Automatically

It is common for a web application, such as webMathematica, to be launched automatically whenever the server machine starts. This section will review the ways that this can be done. Of course this is typically done by the system administrator; the information here is something that can be used to adapt to the conventions of your own system. The instructions are different for Unix and Windows. These instructions will focus on launching Tomcat; if you use some other servlet container, you will need to consult its documentation.

Unix

Tomcat can be launched automatically by adding it to a system startup script. The description here is typical of a Linux RedHat system. It is a good idea to first study the instructions for setting up Tomcat on Unix.

A common way to launch is to add a script to the initialization directory init.d and making a link to the appropriate startup directory (for example rc3.d). The script will make definitions for starting and stopping Tomcat, making use of the tomcat user that was created. A sample script is shown below.

#!/bin/sh
#
# tomcat        This shell script takes care of starting and stopping
#               tomcat.
# description: tomcat is a servlet/JSP engine, which can be used
#              standalone or in conjunction with Apache


# Source function library.
. /etc/rc.d/init.d/functions

# Source networking configuration.
. /etc/sysconfig/network

RETVAL=0

export JAVA_HOME=/usr/local/java
export CATALINA_HOME=/usr/local/tomcat
export PATH=$PATH:/usr/local/bin:$JAVA_HOME/bin

# See how we were called.
case "$1" in
  start)
        # Start daemons.
        echo -n "Starting tomcat: "
        cd ~tomcat
        su tomcat -c '$CATALINA_HOME/bin/catalina.sh start'
        RETVAL=$?
        [ $RETVAL -eq 0 ] && touch /var/lock/subsys/tomcat
        echo
        ;;
  stop)
        # Stop daemons.
        echo -n "Shutting down tomcat: "
        cd ~tomcat
        su tomcat -c '$CATALINA_HOME/bin/catalina.sh stop'
        RETVAL=$?
        [ $RETVAL -eq 0 ] && rm -f /var/lock/subsys/tomcat
        echo
        ;;
  restart)
        $0 stop
        $0 start
        RETVAL=$?
        ;;
  *)
        echo "Usage: tomcat {start|stop|restart}"
        exit 1
esac

exit $RETVAL

In addition, if you are using a virtual X server, such as Xvnc, you will need to launch this at system initialization time. A sample script for launching Xvnc is shown below.

!/bin/sh
#
# description: VNC instance for webMathematica

# Source function library.
. /etc/rc.d/init.d/functions

# Source networking configuration.
. /etc/sysconfig/network

RETVAL=0

# See how we were called.
case "$1" in
  start)
        # Start daemons.
        echo -n "Starting VNC: "
        cd ~tomcat
        su tomcat -c '/usr/bin/vncserver -geometry 800x600 -depth 24 :1 >/dev/null 2>/dev/null'
        RETVAL=$?
        [ $RETVAL -eq 0 ] && touch /var/lock/subsys/vnc
        echo
        ;;
  stop)
        # Stop daemons.
        echo -n "Shutting down VNC: "
        cd ~tomcat
        su tomcat -c '/usr/bin/vncserver -kill :1 >/dev/null 2>/dev/null'
        RETVAL=$?
        [ $RETVAL -eq 0 ] && rm -f /var/lock/subsys/vnc
        echo
        ;;
  restart)
        $0 stop
        $0 start
        RETVAL=$?
        ;;
  *)
        echo "Usage: vnc {start|stop|restart}"
        exit 1
esac

exit $RETVAL

Windows

The way to run programs automatically on Windows is to install them as a service.

Installing Tomcat as a service on Windows is quite easy, since the installer will give you the option of installing it as a service. If you did not choose this as an option when you first installed Tomcat, you can rerun the installer.

You can get extra information about the services you have installed by going to the Administrative Tools icon of the Control Panel. Here you will see a Services icon which you can open. The Services dialog that opens will show the services that have been installed on your machine. You should see one for Tomcat. The dialog will tell you if the service has started or not and will tell you how it is launched. Typically the installer makes it an Automatic startup type that causes it to launch when the computer is booted. Clicking the Tomcat entry and selecting Properties will give you a dialog, that allows you to configure the service.

Running Tomcat as a service works well if the JDK is 1.4. The JDK is found by searching for java.exe on the Windows path, so you need to make sure that the JDK you installed earlier is found.

Web Server Connections

In some configurations, the main accessible server is a regular web server such as the Apache HTTP or the Microsoft Internet Information Server. It is possible to use such a server in conjunction with a servlet container. This type of configuration is more complicated, but can take advantage of many additional features, for example, authentication and URL rewriting, and is often suitable for an existing web infrastructure. This section gives a brief description of configuration for some typical arrangements. It is probably useful to configure your servlet container to work in a standalone mode before starting any of this work.

If you wish to use webMathematica in conjunction with a separate web server, you will need to make sure that all requests to webMathematica are forwarded to the webMathematica web application. This will make sure that requests for applet archives, HTML pages, and images are properly processed. If the server is only set to allow access to servlets, then these other resources will not be accessible.

If you just wish to test webMathematica running directly through a servlet container such as Tomcat, you may skip this section.

Apache and Tomcat

There are a number of ways for the Apache web server to communicate with Tomcat. One convenient way is to use an HTTP forwarding mechanism to send requests from the Apache web server to Tomcat. This can be arranged with the ProxyPass configuration directive. A sample configuration, that could be added to the Apache configuration file (typically called httpd.conf), is shown below.

<IfModule mod_proxy.c>
  <Location /webMathematica/Resources/Tools>
    Order allow,deny
    deny from all
  </Location>

  ProxyPass /webMathematica http://tomcatserver:8080/webMathematica
  ProxyPassReverse /webMathematica http://tomcatserver:8080/webMathematica
</IfModule>

The ProxyPass directive provides a mapping from a path to an external URL, and the ProxyPassReverse directive causes the responses to be modified so that the proxy is transparent. Any access to /webMathematica will be sent to port 8080 on the machine tomcatserver. The configuration also denies access to the kernel monitor via the proxy. The features of the kernel monitor are described in a later section.

For the ProxyPass directive to be effective, the modules mod_proxy and mod_proxy_http must be loaded, this can be done with the following configuration information in the Apache configuration file.

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so

For more information on using Apache and Tomcat, you should consult the websites for Apache, http://httpd.apache.org, and Tomcat, http://tomcat.apache.org/. Note that you can run Apache on both Windows and Unix machines, as well as Mac OS X machines.

Microsoft Servers and Tomcat

If you wish to deploy Microsoft PWS or IIS as your web server, it is possible to use them with Tomcat as a servlet container.

Tomcat comes with instructions for configuring it as a servlet container for IIS and PWS. The configuration has to be done manually, and, although straightforward, it has a number of steps that must be followed carefully and involves editing the Windows registry by hand.

You need to make sure that you edit the workers.properties file, found in the Tomcat conf directory, to give values to workers.tomcat_home and workers.java_home. The required settings will be clear from the description in the file.