A typical webMathematica installation will require the following steps:

You may also need steps for upgrading from webMathematica 3.1 or for further optional configuration, or wish to browse additional resources.

Setting Up a Servlet Container

You must set up Java and a servlet container before adding webMathematica. If you already have these components, you can skip this step.

There are several servlet containers, but one that is particularly convenient to use with webMathematica is Apache Tomcat. The following instructions assume the use of Tomcat, but keep in mind that other servlet containers may be used with webMathematica.

Setting Up Java

We recommend that you use one of the latest versions of Java with webMathematica. The Java download website provides detailed installation instructions for different platforms.

You will also need to set the JAVA_HOME environment variable for the environment in which Tomcat runs:

Linux

Here is an example, suitable for inclusion in .bashrc (the initialization file for the bash shell):

JAVA_HOME=/usr/local/jdk1.6.0_34
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 System, you will see the System Properties window. From this, select the Advanced tab, then click the Environment Variables button. Under System Variables, look for a JAVA_HOME listing. Edit or create it, as applicable, setting it to the top-level directory containing your Java Development Kit (JDK). For example, if your JDK is installed in C:\Program Files\Java\jdk1.6.0_34, this is the setting for JAVA_HOME.

Mac OS X

Mac OS X ships with Java. Updates can be obtained via the software update mechanism or from Oracle’s Java website (or from Apple for Mac OS X 10.6 only). If you update your Java installation, you can ensure that you are always using the most recent version of the Java Development Kit (JDK) by setting up the JAVA_HOME environment variable properly, as shown here:

JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Home
export JAVA_HOME

The above command needs to be placed in the appropriate shell initialization file. For example, the default login shell is bash, for which the command would be placed in .bashrc.

Setting Up Tomcat

Before you set up Tomcat, make sure you have Java on your machine. For webMathematica 3.2, we recommend the use of Tomcat 5.5.27 or higher.

Linux

Unpack the Tomcat archive 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. Here are sample shell instructions for these steps:

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

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

[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, and 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. The log files may help you track down your problem. Make sure that you have set your JAVA_HOME variable correctly.

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

Windows

A convenient way to install Tomcat is to download the self-installing executable—simply 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.

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

  • Tomcat 5.5
  • 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, and 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 tomcat5.exe executable file (this can also be accomplished by double-clicking on the file via the Windows Explorer). Previous versions of Tomcat used a startup.bat batch file. Starting and stopping Tomcat from the Start menu is very convenient, but for running Tomcat as a production server under Windows, you may wish to run it as a Windows service.

Mac OS X

It is often useful 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 this account can run it:

[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, and 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. The log files may help you track down your problem. Make sure that you have set your JAVA_HOME variable.

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

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

Unpack the Tomcat archive 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.

Here are sample shell instructions for these steps (note that the 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-5.5.27.tar.gz
[server1]$ sudo mv jakarta-tomcat-5.5.27 tomcat

Installing and Configuring Mathematica

Install the version of Mathematica appropriate for the platform you wish to use for your web server. You should choose a single-machine installation. Installation instructions are available at the Wolfram Technical Support Center. When you have finished, you should be able to run Mathematica interactively to validate your installation. If Mathematica cannot run, then webMathematica cannot run.

If you already have an installation of Mathematica on your server, you do not need to install Mathematica again and can proceed with the remaining installation steps. With an existing installation of Mathematica, you should place your webMathematica license information into a different location. Placing the license information in a different location will ensure that an interactive usage of Mathematica on your server does not interfere with the operation of your webMathematica site. One possible alternative is the webMathematica/WEB-INF/conf directory. Note that if you install the license in a special file, you will have to set the -pwfile option the first time you run Mathematica outside of webMathematica.

Installing the webMathematica Web Application

Installing the webMathematica components into your servlet container involves deploying the webMathematica web application. The web application is a collection of HTML and other web components that are placed in a specific directory structure. Any servlet container that supports web applications will be able to use these files in a standard way. Web applications can use a special WAR (web application archive) file format, which is supported by some servlet containers. The webMathematica CD-ROM and download include the webMathematica web application files in both .war and .zip format. These archive contents are identical; use whichever is supported by your system, and ignore the other.

Tomcat

Unpack one of the webMathematica web application archives into the webMathematica directory located in the Tomcat webapps directory. This is usually found in the top-level directory of Tomcat. You have now created a web application called web Mathematica. Some of the contents of the top directory of Tomcat, along with the location of the webapps directory and web Mathematica web application, are shown here:

  • tomcat
  • conf
  • bin
  • logs
  • lib
  • webapps
  • webMathematica

Second, configure the file MSPConfiguration.xml, located in the WEB-INF/conf directory. This file holds various site-specific parameters and may need modification for your site.

The most important setting is KernelExecutable, the location of the Mathematica kernel. The MSPConfiguration.xml file that ships with webMathematica contains settings suitable for a default installation of Mathematica for Windows, Linux, and Mac OS X. However, if you install Mathematica into a nondefault location, you will need to modify this file. For example, if you installed Mathematica into E:\Mathematica, make the following setting of KernelExecutable in MSPConfiguration.xml.

<KernelExecutable>
E:\Mathematica\MathKernel.exe
</KernelExecutable>

Another reason to modify MSPConfiguration.xml is to store your webMathematica license information in its own password file, for example webMathematica/WEB-INF/conf/mathpass. It would then be necessary to modify KernelLaunchFlags in MSPConfiguration.xml to ensure that Mathematica uses this location. The following shows how this could be done for a typical Windows installation:

<KernelLaunchFlags>
-pwfile c:/Program Files/tomcat/webapps/webMathematica/WEB-INF/conf/mathpass
</KernelLaunchFlags>

A typical setting for MSPConfiguration.xml to use a special mathpass file under Linux is shown here:

<KernelLaunchFlags>
-pwfile /usr/local/tomcat/webapps/webMathematica/WEF-INF/conf/mathpass
</KernelLaunchFlags>

Under Linux, you may need to add a KernelLaunchFlags parameter so the front end can run properly. In the following example, the front end will be launched to use DISPLAY 1 with fixed geometry and in server mode.

 <FrontEndLaunchFlags>
-display :1 -nogui -geometry 1000x500+10+10
</FrontEndLaunchFlags>

Other Servlet Engines

If you are unfamiliar with servlets, then we recommend that you use Tomcat. You should only use another servlet engine if you are already experienced with it.

Setting Up an X Window System (Linux Only)

There are special problems associated with running the Mathematica front end under X from within a web server. This is because, typically, the web server is run as a special account, such as “tomcat”. This means that when webMathematica runs the front end, it is running under this account.

For the front end to operate, it must connect to an X server. This could be achieved by logging into the console of the web server machine with this special account running an X server, but there are a few problems with this approach. First, you may not want to leave the machine with an open login on the console; second, every time the front end does something, a window will appear on the screen, which may be distracting for someone using the machine. Finally, if a different user logs into the console and runs an X server, the front end (which is run under the special webMathematica account) will not be able to connect to this server at all under X’s standard authentication system. While it is possible to configure the server to allow these connections, it is not satisfactory because webMathematica will display windows on the screen every time it does something with the front end.

These problems are solved by running a virtual X server, such as Xvnc, which prevents the windows created by the Mathematica front end from displaying on the screen console of the computer running Mathematica.

Detailed instructions about configuring Xvnc and webMathematica are available in the webMathematica User Guide.

Upgrading from webMathematica 3.1

To upgrade from webMathematica 3.1, simply follow the steps below. If you are using an older servlet container, this may be a good opportunity to upgrade to something more recent. If you are going to upgrade your servlet container, you can follow the instructions at the beginning of this page as though this is a fresh installation of webMathematica.

Install Mathematica

Install Mathematica 9.0 on your web server. If you have installed any applications into your previous copy of Mathematica, you will need to make them available to the new Mathematica installation. Note that you should not copy the MSP application to Mathematica.

Install the webMathematica Web Application

To install the webMathematica web application, you will need to remove your current webMathematica web application from your servlet container. For Tomcat, this is a simple matter of moving the webMathematica directory from the webapps directory. You may need some of the material in this web application, so you should probably keep it somewhere accessible.

Configure the New Layout

If you made any special configuration changes to your old version of webMathematica, you may want to make similar changes in webMathematica 3.2. Typically this might affect the file web.xml, as well as the webMathematica and security configuration files.

web.xml

You should only make changes to web.xml if you are certain that you understand the intent of the setting. In addition, it would be better to copy any modified configuration parameters from the old version rather than taking the entire file. The web.xml file is found in the directory webMathematica/WEB-INF.

MSPConfiguration.xml

webMathematica uses a configuration system based on an XML file called MSPConfiguration.xml, which is found in the directory webMathematica/WEB-INF. You should copy specific configuration parameters rather than taking the entire file.

Security Configuration

The mechanism for locating the security configuration file has changed. The security configuration file is now named in the pool configuration and is located in a central configuration directory in webMathematica/WEB-INF; the default name is SecurityConfiguration.m. Previously the configuration file could be loaded from anywhere on the Mathematica path.

This change was made because loading the security configuration from a single central location is more secure. As the default security system of webMathematica is very conservative, any sites that do not move their security files will run with a higher level of security than is expected.

Move Content to the New Layout

Now you should copy your content from your old layout. You should not copy any of the examples, because webMathematica 3.2 has its own set of updated examples. Instead, you should just copy your own material from the old layout into the new.

Finalize the Installation

When you have installed the new version of webMathematica you should test your installation. A good URL to use is http://localhost:8080/webMathematica/Examples/Specification.jsp. This will print the version numbers of your installation. You should confirm that you have webMathematica 3.2 and Mathematica 9.0.

Further Configuring (Optional)

There are a number of additional features that can be obtained following a few extra installation steps, but it is not necessary to carry them out to run your webMathematica server.

Testing Your webMathematica Installation

You should now be able to restart your server and connect to webMathematica. Note that you may have to modify the URLs shown in this document to connect to your servlet container; for example, the URL may require a different port number from 8080, which is the default port for direct access to Tomcat. The URL that you use to test your servlet container will show the correct URL to use for webMathematica. In addition, you should note that the URL is case sensitive, so make sure to type in capitals as they appear.

You may first want to connect to the webMathematica front page via http://localhost:8080/webMathematica. This page contains links to examples, documentation, templates, images, and external references.

After this, it may be good to try some of the active examples, such as Expand, which can be reached from a link on the front page and from a URL such as http://localhost:8080/webMathematica/BrowseExamples/Expand.html. Enter parameters into the input fields and click Evaluate.

It may also be a good idea to test a graphics example, such as http://localhost:8080/webMathematica/Examples/Plot.jsp. If you are running on Linux, you will need to specifically configure your X server to generate graphics and use other features of the Mathematica front end. It is a good idea to test that this works correctly.

Additional Resources

For additional installation assistance, see the webMathematica User Guide, or contact
Advanced Technical Support.