Mathematica 9 is now available
2.1 Setting up a Servlet Container

Documentation2. Installation

 

2.1 Setting up a Servlet Container

Before you start to install webMathematica, you need an installation of Java and a servlet container. If you already have these components, you may skip this section.

There are many different servlet containers, but one that is particularly convenient is Tomcat, which can be obtained from http://jakarta.apache.org. Another popular server container is JRun, http://www.macromedia.com/software/jrun/. Since Tomcat is a common way to run webMathematica, we have added information on installing and setting it up on Unix and Windows.

webMathematica has been tested with both Tomcat and JRun as well as other containers listed at http://www.wolfram.com/products/webmathematica/technology/specifications.html. If you have a particular interest or experience in running webMathematica with other containers, please contact Wolfram Research. However, if you do not have expertise with these other containers, we recommend you use Apache Tomcat.

When your servlet container is functioning correctly, as demonstrated by running its sample servlets, you are ready to install webMathematica. If your servlet container does not work, then webMathematica cannot work. The remaining steps in this section show you how to set up Java and Tomcat. If you are not using Tomcat you should skip this section and study the documentation for your servlet container.

2.1.1 Setting up Java

Any Java Development Kit that supports Java Version 1.2 (or later) can be used. However, it is recommended that you use a modern version of Java, such as Java 2 Version 1.4. For Windows 2000/NT/XP, Linux, or Solaris, these are available from the Sun Java site at http://java.sun.com/j2se/1.4.1/download.html. The Sun Java site provides detailed installation instructions for the different platforms. These are all relatively simple; typically, you download and execute an installer. To run webMathematica you need the Java Development Kit (JDK). For Mac OS X, Java 2 Version 1.3 is already installed. For other platforms, modern versions of Java are available from the appropriate vendors; a list of useful links is maintained in the Links Appendix: Java.

You will also need to set the JAVA_HOME environment variable. This is described in the next sections for Unix and Windows.

Unix

The JAVA_HOME environment variable needs to be set for the environment in which Tomcat runs. An example of this, suitable for inclusion in .bashrc (this is the initialization file for the bash shell), is shown below.

JAVA_HOME=/usr/local/j2sdk1.4
export JAVA_HOME

For other shells, you should follow their standards for setting environment variables.

Windows

It is less important to set the JAVA_HOME variable for Windows because the Tomcat installer will find your installation of Java. However, it is still recommended.

If you go to the Control Panel and open the System icon, you will see the System Properties window. From this, select the Advanced tab and then the Environment Variables button. Enter JAVA_HOME as a system variable, setting it to the top-level directory containing your JDK. For example, if your JDK is installed in c:\j2sdk1.4.0_01, this is the setting for JAVA_HOME.

Mac OS X

Mac OS X 10.2 was originally shipped with Java 2 Version 1.3.1. The JDK has recently been updated to version 1.4.1, which can be obtained via the software update mechanism (see also http://www.apple.com/java/). You can ensure that you are always using the most recent version of the JDK by setting up the JAVA_HOME environment variable properly; this is shown below.

setenv JAVA_HOME /System/Library/Frameworks/JavaVM.framework/Home

The default login shell for Mac OS X is tcsh; hence, the above command needs to be placed in the appropriate shell initialization file, for example, .tcshrc.

2.1.2 Setting up Tomcat

This section describes setting up Tomcat on Unix and Windows. The main web site for Tomcat is http://jakarta.apache.org; a list of useful links is maintained in Links Appendix: Tomcat.

Unix

Before you run Tomcat, you should first make sure you have set up a JDK on your machine; this was described in the previous section.

Download information for current versions of Tomcat is given at http://documents.wolfram.com/webmathematica/updates/install/tomcat/current. A variety of archive formats are available; one of these should be unpacked in some central location, for example /usr/local. You may also wish to change the name of the top-level directory. The actual location of Tomcat and the name of the top-level directory are entirely up to you. Sample shell instructions for these steps are shown below (note that tar xvfz archive will give you more information on what files are being extracted). Other versions of Tomcat are available from the Apache web site, http://jakarta.apache.org.

[server1]$ cd /usr/local
[server1]$ tar xfz jakarta-tomcat-4.1.18.tar.gz
[server1]$ mv jakarta-tomcat-4.1.18 tomcat

On some platforms, such as Solaris, the default tar command does not work to unpack the Tomcat archive as shown above. One would need to obtain the GNU tar utility from http://www.gnu.org/directory/GNU/tar.html in order to use the options shown.

It is often useful to create a low privilege account, such as tomcat, to run your servlet container. It is probably helpful if this account has a home directory so that your X server and Mathematica can store preferences information. If you create such an account, you may need to change ownership of the Tomcat layout so it can be run by this account.

[server1]$ chown -R tomcat tomcat

The main top-level directory of Tomcat contains some important directories, including:

tomcat
bin
   conf   
   logs
   webapps

The bin directory contains commands for running Tomcat; the conf directory contains site configuration files; the logs directory contains various log files; the webapps directory is where you will install webMathematica. You should be able to launch Tomcat immediately from the bin directory, making sure to be the tomcat user.

[server1]$ su tomcat
[server1]$ cd tomcat/bin
[server1]$ ./startup.sh

At this point, you should be able to connect to Tomcat via a URL such as http://localhost:8080. If this does not return the Tomcat front page, then something is wrong with your setup. If you look at the log files, it may help you track down your problem. Make sure that you have set your JAVA_HOME variable as described in the installing Java for Unix section.

The bin directory also contains a script, shutdown.sh, used for shutting down Tomcat.

Information on launching Tomcat automatically on Unix is given in a later section.

Windows

Before you run Tomcat, you should first make sure you have set up a JDK on your machine; this was described in the previous section.

Download information for current versions of Tomcat is given at http://documents.wolfram.com/webmathematica/updates/install/tomcat/current. A convenient way to install Tomcat is to download the self-installing executable. You should launch the installer and follow the instructions it provides. If you choose not to use the self-installing executable, then unpack the binary distribution into a convenient location. Other versions of Tomcat are available from the Apache web site, http://jakarta.apache.org.

After installation is complete, you may wish to inspect the main top-level directory of Tomcat, which contains some important directories, including:

tomcat
bin
   conf   
   logs
   webapps

The bin directory contains commands for running Tomcat; the conf directory contains site configuration files; the logs directory contains various log files; the webapps directory is where you will install webMathematica.

The installer adds a Start Menu Group from which you can run Tomcat. You should test it via a URL such as http://localhost:8080. If Tomcat does not run correctly, you should open a command prompt window, change directories ("cd") to the bin directory (in the main top-level directory of Tomcat) and try running the startup.bat batch file (this can also be accomplished by double-clicking on the file via the Windows Explorer). Starting and stopping Tomcat from the Start Menu is very convenient (this is also a new feature of Tomcat 4.1), but for running Tomcat as a production server under Windows you may wish to run it as a Windows Service. This is described in the section on launching Tomcat automatically on Windows.

Mac OS X

Before you run Tomcat, you should first make sure you have set up a JDK on your machine; this was described in the previous section.

Download information for current versions of Tomcat is given at http://documents.wolfram.com/webmathematica/updates/install/tomcat/current. A variety of archive formats are available; one of these should be unpacked in some central location, for example /Library. You may also wish to change the name of the top-level Tomcat directory. The actual location of Tomcat and the name of the top-level directory are entirely up to you. /Library is useful because it can be viewed via the Finder. Other versions of Tomcat are available from the Apache web site, http://jakarta.apache.org.

Note that the default OS X tar command does not work to unpack the Tomcat archive as shown below. One would need to use the GNU tar utility (gnutar), which should reside in /usr/bin/, to use the options shown. One could also use Stuffit Expander (version 7.0.1 and later) which uncompresses *.tar.gz archives.

Sample shell instructions for these steps are shown below (note that tar xvfz archive will give you more information on what files are being extracted). These instructions assume that you are using the Terminal application found in Applications-> Utilities-> Terminal.

[server1]$ cd /Library
[server1]$ sudo /usr/bin/gnutar xfz jakarta-tomcat-4.1.18.tar.gz
[server1]$ sudo mv jakarta-tomcat-4.1.18 tomcat

It is often good to create a low privilege account, such as tomcat, to run your servlet container. You can accomplish this via the System Preferences panel. If you create such an account, you may need to change ownership of the Tomcat layout so it can be run by this account.

[server1]$ sudo chown -R tomcat tomcat

The main top-level directory of Tomcat contains some important directories, including:

tomcat
bin
   conf   
   logs
   webapps

The bin directory contains commands for running Tomcat; the conf directory contains site configuration files; the logs directory contains various log files; the webapps directory is where you will install webMathematica. You should be able to launch Tomcat immediately from the bin directory, making sure to be the tomcat user.

[server1]$ su tomcat
[server1]$ cd tomcat/bin
[server1]$ ./startup.sh

At this point, you should be able to connect to Tomcat via a URL such as http://localhost:8080. If this does not return the Tomcat front page, then something is wrong with your setup. If you look at the log files, it may help you track down your problem. Make sure that you have set your JAVA_HOME variable as described in the installing Java for Mac OS X section.

The bin directory also contains a script, shutdown.sh, used for shutting down Tomcat.

Please also note that for webMathematica to fully function, one would need to log on via the Mac OS X console. This is necessary since the Mathematica front end makes use of the Mac OS X windowing environment.



Any questions about topics on this page? Click here to get an individual response.Buy NowMore Information
THIS IS DOCUMENTATION FOR AN OBSOLETE PRODUCT. CURRENT WEBMATHEMATICA DOCUMENTATION IS NOW AVAILABLE.