2. Installation
| Documentation2. Installation |
   |
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.
Any Java Development Kit (JDK) 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 NT/2000/XP, Linux, or Solaris, these are available from the Sun Java site at http://java.sun.com/j2se/downloads/index.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 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 Appendix: Java.
You will also need to set the JAVA_HOME environment variable. This is described in the next sections for Unix and Windows.
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.
It is recommended to set the JAVA_HOME environment variable for the environment in which Tomcat runs. This can be done with a script used to launch Tomcat or more conveniently with the Control Panel.
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:\j2sdk, this is the setting for JAVA_HOME.
It can also be useful to amend the PATH environment variable to include the directory that contains the jawt.dll library. Typically this is found in JAVA_HOME/jre/bin.
Mac OS X 10.3 ships with Java 2 Version 1.4.1. 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.3 is bash; hence, the above command needs to be placed in the appropriate shell initialization file, for example, .bashrc.
Mac OS X 10.2 was originally shipped with Java 2 Version 1.3.1, but updates are available from 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.
setenv JAVA_HOME /System/Library/Frameworks/JavaVM.framework/Home
The default login shell for Mac OS X 10.2 is tcsh; hence, the above command needs to be placed in the appropriate shell initialization file, for example, .tcshrc.
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 Appendix: Tomcat.
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-5.0.28.tar.gz
[server1]$ mv jakarta-tomcat-5.0.28 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.
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.
Of course, before you run Tomcat, you should first make sure you have set up a JDK on your machine as described in the previous section.
Mac OS X 10.3 already includes a version of Tomcat, which is located in /Library/Tomcat. Therefore, there is no need to obtain and install Tomcat.
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 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 
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.
Tomcat is not already installed on versions of Mac OS X older than 10.3. 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. 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.0.28.tar.gz
[server1]$ sudo mv jakarta-tomcat-5.0.28 tomcat
|