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 https://tomcat.apache.org. Since Tomcat is a common way to run webMathematica, there is information on installing and setting it up on Linux, Windows, and Mac OS X.
webMathematica has been tested with Tomcat. If you have a particular interest in running webMathematica with other containers, please contact Wolfram Research. However, if you do not have expertise with these other containers, using Apache Tomcat is recommended.
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.
Setting Up Java
It is required that you use Java version SE 5 or higher, and use of a modern version such as Java SE 7 is recommended. Except for users running Mac OS X 10.6, this is available from the Oracle Java site at https://www.oracle.com/technetwork/java/javase/downloads/index.html. For Mac OS X 10.6, Java is available from Apple through https://support.apple.com/kb/DL1573. These sites provides detailed installation instructions for the different platforms. These are all relatively simple; typically, you download and execute an installer.
You will also need to set the JAVA_HOME environment variable. This is described in the next sections for Linux, Windows, and Mac OS X.
Linux
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.
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:\Program Files\Java\jdk1.6.0_34, this is the setting for JAVA_HOME.
Mac OS X
If you update your 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.
JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Home
export JAVA_HOME
To avoid setting this each time you start Tomcat, place the above command in your shell initialization file, for example, .bashrc.
Setting Up Tomcat
This section describes setting up Tomcat on Linux, Windows, and Mac OS X. The main website for Tomcat is https://tomcat.apache.org; a list of useful links is maintained in Appendix: Tomcat.
Linux
Before you run Tomcat, you should first make sure you have set up Java on your machine; this was described in the previous section.
Download information for Tomcat is available from the Apache website at https://tomcat.apache.org/. 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).
[server1]$ cd /usr/local
[server1]$ tar xfz apache-tomcat-5.5.27.tar.gz
[server1]$ mv apache-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 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.
The main top-level directory of Tomcat contains some important directories, including:
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.
At this point, you should be able to connect to Tomcat via a URL such as https://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 Linux section.
The bin directory also contains a script, shutdown.sh, used for shutting down Tomcat.
Information on launching Tomcat automatically on Linux is given in a later section.
Windows
Before you run Tomcat, you should first make sure you have set up Java on your machine; this was described in the previous section.
Download information for Tomcat is available from the Apache website at https://tomcat.apache.org/. 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.
After installation is complete, you may wish to inspect the main top-level directory of Tomcat, which contains some important directories, including:
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 https://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. This is described in the section on launching Tomcat automatically on Windows.
Mac OS X
Of course, before you run Tomcat, you should first make sure you have set up Java on your machine as described in the previous section.
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 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 https://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, you 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.
Download information for Tomcat is available from the Apache website at https://tomcat.apache.org/. 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.
Note that the default OS X tar command does not work to unpack the Tomcat archive as shown below. You would need to use the GNU tar utility (gnutar), which normally resides in /usr/bin/, to use the options shown. You 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 apache-tomcat-5.5.27.tar.gz
[server1]$ sudo mv apache-tomcat-5.5.27 tomcat