2.3 Installing the webMathematica Web Application
This section describes how to install webMathematica components into your servlet container. For most servlet containers, this involves deploying the webMathematica web application found in archived form on the webMathematica Tools CD-ROM. Separate installation instructions are given for some different servlet containers. A web application is a collection of HTML and other web components, which 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 support a special type of archive called a WAR archive, which is supported by some servlet containers. The webMathematica Tools CD-ROM provides a WAR archive of the webMathematica archive; the contents of the archive is given in the Appendix: File Layout.
2.3.1 If You Use Tomcat
This section describes the deployment of the webMathematica webapp in Tomcat. There are two steps: unpacking the webMathematica archive and configuring the MSP.conf file.
First, choose one of the webMathematica archives from the Tools CD-ROM; for example, webMathematica.zip or webMathematica.tar.gz. Unpack 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 webMathematica. The contents of the webMathematica web application are described later in the appendix. Some of the contents of the top directory of Tomcat, along with the location of the webapps directory and webMathematica web application, are shown below.
Second, configure the file MSP.conf, located in the WEB-INF/conf directory. This file holds various site-specific parameters and may need modification for your site. The settings that can be placed into MSP.conf are described in the section Site Configuration.
The most important setting is MathLinkArguments, the command that launches Mathematica. The MSP.conf that ships with webMathematica contains settings suitable for a default installation of Mathematica for Windows, Unix, Linux, and Mac OS X. However, if you install Mathematica into a non-default location, you will need to modify this file. For example, if you installed Mathematica into E:\Mathematica, make the following setting of MathLinkArguments in MSP.conf (note the backslashes).
MathLinkArguments=-linkname 'E:\\Mathematica\\MathKernel.exe -mathlink' -linkmode launch
Another reason to modify MSP.conf is to store your webMathematica license in its own password file, for example, webMathematica/WEB-INF/conf/mathpass. It would then be necessary to modify MSP.conf to ensure that Mathematica uses this location. The following shows how this could be done for a typical Windows installation.
MathLinkArguments=-linkname 'c:\\Program Files\\Wolfram Research\\Mathematica\\4.2\\MathKernel.exe -mathlink -pwfile "c:/Program Files/tomcat/webapps/webMathematica/WEB-INF/conf/mathpass"' -linkmode launch
A typical setting for MSP.conf to use a special mathpass file under Unix is shown below.
MathLinkArguments=-linkname 'math -mathlink -pwfile /usr/local/tomcat/webapps/webMathematica/WEF-INF/conf/mathpass' -linkmode launch
Under Unix, you may need to add a FrontEndLaunchCommand 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. For more information on running the front end under Unix, see the documentation section Configuring for the X Window System.
FrontEndLaunchCommand=mathematica -mathlink -display :1 -nogui -geometry 1000x500+10+10
2.3.2 If You Do Not Use Tomcat
JRun is a sophisticated application server. It contains a web-based wizard to guide you through the installation process. You will need to follow JRun-specific instructions to install the webMathematica web application that are given in this section. Please note that you need to use JRun 4.0 or higher in order to use the webMathematica custom tags. If you use JRun 3.x, you can still use webMathematica as described in the section on Classic webMathematica Technology. These installation instructions are appropriate for JRun 4.
First, unpack the webMathematica archive into a location on your server that is accessible by JRun, e.g. E:\webMathematica. At this time you can make any necessary changes to MSP.conf. For example, you may wish to set the MathLinkArguments or the FrontEndLaunchCommand as described in the section for installing into Tomcat.
Now use the JRun Management Console, which under Windows is accessible via Start->Programs->Macromedia JRun4->JRun Management Console. Alternatively, you can use the URL http://localhost:8000. You will need to enter the username and password that were specified when JRun was installed. Once you gain access, click on the default link on the left frame to expand its contents. In the main frame, you should see information about the default server, which has the title J2EE Components on default.
Click on the add button under Web Applications to add the webMathematica web application. You will see a new page, entitled Deploy Web Application, with a field called Source File Path. Click on the Browse button - this will bring up a file browsing window. Navigate to the location (e.g. E:\webMathematica) where you have extracted the files from the webMathematica archive. Select the webMathematica folder icon, and click on the Open button. This will change the Source File Path to E:\webMathematica. You can now click on Deploy. After a few moments, you will see a screen that allows you to customize various details of the installation, depending on the version of JRun that you are using. You can choose the default values and then click the Apply button. A message informing you that the deployment of webMathematica has been successful will appear.
At this point you should be able to test your installation as described in the Testing section. Note that the default port for JRun is 8100, so a URL such as http://localhost:8100/webMathematica, should access the webMathematica front page.
Other Servlet Engines
If you are unfamiliar with servlets then it is recommended that you use Apache Tomcat. You should only use another servlet engine if you are already experienced with it.
If you have some other servlet engine, follow its instructions for installing a web application, which may be supported by some special tools. After installing the web application, you will need to modify the MSP.conf file as described in the section on installing under Tomcat. It may also be necessary to make various modifications to MSP.conf, such as changing the WebApplicationName or the JLinkNativeLibraryDirectory settings. These are described in Appendix: MSP.conf.