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. Since Tomcat is a common way to run webMathematica, there is information on installing and setting it up on Unix, Windows, and Mac OS X.
webMathematica has been tested with Tomcat as well as other containers listed at http://www.wolfram.com/products/webmathematica/technology/. 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, 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 recommended that you use a modern version of Java, such as Java SE 6. For Linux, Linux x64, Solaris SPARC, Solaris x64, Solaris x86, Windows, and Windows x64, this is available from the Sun Java site at http://java.sun.com/javase/downloads/index.jsp. The Sun Java site provides detailed installation instructions for the different platforms. These are all relatively simple; typically, you download and execute an installer. If you are using Java SE 5 or higher, you can use either a JRE or JDK to run webMathematica. If you are using an older version of Java, you need the JDK. For Mac OS X, J2SE 5.0 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 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.
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_14, this is the setting for JAVA_HOME.
Mac OS X
Mac OS X 10.5 ships with J2SE 5.0 and Java SE 6. Mac OS X 10.4 ships with J2SE 5.0. You may find that an updated version can be obtained via the software update mechanism (see also http://www.apple.com/java/). 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
The default login shell for Mac OS X 10.5 is bash; hence, the above command needs to be placed in the appropriate shell initialization file, for example, .bashrc.
Setting Up Tomcat
This section describes setting up Tomcat on Unix, Windows, and Mac OS X. The main website for Tomcat is http://jakarta.apache.org; a list of useful links is maintained in Appendix: Tomcat.
Unix
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 current versions of Tomcat is given at http://www.wolfram.com/products/webmathematica/resources/?tab=Updates. 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 website, http://jakarta.apache.org.
[server1]$ cd /usr/local
[server1]$ tar xfz jakarta-tomcat-5.5.27.tar.gz
[server1]$ mv jakarta-tomcat-5.5.27 tomcat
On some platforms, such as Solaris, the default tar command does not work to unpack the Tomcat archive as shown above. You 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.
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 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.
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 Java on your machine; this was described in the previous section.
Download information for current versions of Tomcat is given at http://www.wolfram.com/products/webmathematica/resources/?tab=Updates. 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 website, 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:
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 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 (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
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
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.
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 current versions of Tomcat is given at http://www.wolfram.com/products/webmathematica/resources/?tab=Updates. 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 website, http://jakarta.apache.org.
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 jakarta-tomcat-5.5.27.tar.gz
[server1]$ sudo mv jakarta-tomcat-5.5.27 tomcat
