Read this article in: Deutsch, Español, Français, 日本語, 한국어, Português, Русский, 中文

web Mathematica requires that Java, a Servlet container and Mathematica are installed on your system. This guide walks you through the following steps to get web Mathematica installed and running on macOS:

1. Setting Up Java
2. Setting Up Tomcat
3. Setting Up Mathematica
4. Making Licensing Files Accessible to web Mathematica
5. Installing and Setting Up web Mathematica

Setting Up Java

Download and run the Java installer.
 

Setting Up Tomcat

Installation

1. Go to http://tomcat.apache.org/download-80.cgi.
2. Download the installer in the format of tar.gz.
3. Change to the location where you wish to install the server. For example, if you wanted to install at /usr/local, execute:

   cd /usr/local

4. Unpack the installer in the current location:

   tar -xvzf apache-tomcat-<version>.tar.gz

Testing Tomcat

1. To start the Tomcat server, in the Tomcat installation directory, execute:

   ./bin/startup.sh

2. Open a web browser and submit “localhost:8080”. If Tomcat has been set up correctly, a page similar to the following one appears:
   
   
3. To shut down the Tomcat server for now, in the same directory, execute:

   ./bin/shutdown.sh

Common possible issues:

• The computer’s firewall is blocking requests to tomcat. Tomcat, by default, runs on port 8080. Ensure that the port is open to accept tcp packets on the system running the Tomcat server.
• If you downloaded Java from Oracle’s website, the Tomcat server may not be able to find the Java installation. In such a case, set the system variable JAVA_HOME to Java’s installation directory, e.g. by executing the following on a bash command line or by adding these lines to .bashrc, if your Java was installed in /Applications/jdk1.8.0 :

  JAVA_HOME=/Applications/jdk1.8.0
  export JAVA_HOME

Creating a Tomcat Account (Recommended)

It is recommended that you set up a dedicated user account to run the Tomcat server, typically called “tomcat”. This account needs the permissions to run the Tomcat server.

1. To create the account, add a user.
2. Change the ownership of the Tomcat installation directory to the “tomcat” user by executing this command from the parent directory of where you installed the apache-tomcat server:

   sudo chown -R tomcat apache-tomcat-<version>

3. Using the new account, start the server:

   su tomcat
   cd apache-tomcat-<version>/bin
   ./startup.sh

4. Open a web browser and submit “localhost:8080”. If the user has been set up correctly, this Tomcat landing page appears again:
   
   

Setting Up Mathematica

You will need to install Mathematica, activate Mathematica and move Mathematica's licensing information into a location that can be accessed globally on your machine.

Installation

Follow the instructions for installing Mathematica on macOS.

Activation

Activate Mathematica using online or manual activation.

Making Licensing Files Accessible to web Mathematica

By default, Mathematica places its licensing information in a mathpass file in a user-specific location. To make your licensing information accessible to your web Mathematica, copy the mathpass file into the globally accessible base directory of Mathematica and set its permission so that any account can read the file.

1. To identify the location of your mathpass file, evaluate in Mathematica:

   $PasswordFile

2. To identify the base directory location, evaluate:

   $BaseDirectory

For example:

In[1]:= $PasswordFile                                                          

Out[1]= /Users/<username>/Library/Mathematica/Licensing/mathpass

In[2]:= $BaseDirectory                                                          

Out[2]= /Library/Mathematica

These folder locations are used in the following instructions.

1. The Licensing directory may not yet exist. If so, create it by executing the following command:

    sudo mkdir -p /Library/Mathematica/Licensing

2. Copy the mathpass file to the Licensing directory of the base directory:

   sudo cp /Users/<username>/Library/Mathematica/Licensing/mathpass /Library/Mathematica/Licensing/mathpass

3. Grant read access to the mathpass file for all accounts:

    sudo chmod a+r /Library/Mathematica/Licensing/mathpass

Installing and Setting Up web Mathematica

Installation

1. Download web Mathematica’s installation file from your User Portal and unzip it to ensure it is opened and unpacked.
2. Place the unzipped web Mathematica directory into the webapps directory of your Apache Tomcat server, where $TOMCAT_INSTALL is the installation directory of your Tomcat server:

   sudo mv webMathematica $TOMCAT_INSTALL/webapps/

3. If you created a tomcat user to run the server, also change the ownership of the web Mathematica folder:

   sudo chown -R tomcat $TOMCAT_INSTALL/webapps/webMathematica

4. Restart the server from the account that owns the folder:

   su tomcat
   cd $TOMCAT_INSTALL/bin
   ./shutdown.sh
   ./startup.sh

Testing and Troubleshooting

The web Mathematica package comes with some default pages that can be used to test the setup of web Mathematica.

1. Access the base page by pointing a browser to “localhost:8080/webMathematica”.
   
   
2. As a first test, click the Hello World example. The Hello World page providing the current time and date appears.
   
   
3. If Hello World is not working, check the log file by executing:

   less $TOMCAT_INSTALL/logs/webMathematica.log

Common possible issue:

Search the log file for error ....com.wolfram.kerneltools.state.StateMachine [ERROR] Could not find MathLink executable. In such a case, web Mathematica could not find the executable of the Mathematica kernel. This can occur if you have installed Mathematica in a non-standard location or if your web Mathematica is not paired with its recommended Mathematica version, e.g. web Mathematica 3.5.3 with Mathematica 12.3. For the recommended pairings of other currently supported product versions, see here.

To point to the correctly paired version of Mathematica, configure web Mathematica.

1. On the command line, go to $TOMCAT_INSTALL/webapps/webMathematica/WEB-INF/ and locate the file MSPConfiguration.xml.
2. Open MSPConfiguration.xml in a text editor and locate the following section:

   <KernelPool>
         <KernelPoolName>General</KernelPoolName>
         <URLPattern>/*</URLPattern>
   </KernelPool>

3. Edit and change this section to:

   <KernelPool>
         <KernelPoolName>General</KernelPoolName>
         <KernelExecutable>
          /Applications/Mathematica.app/Contents/MacOS/MathKernel
         </KernelExecutable>
         <URLPattern>/*</URLPattern>
   </KernelPool>

Note: These instructions assume Mathematica was named “Mathematica.app”. If you have a different application name, substitute the name you used.