Installation of Wolfram Web Engine
Installation with Docker
The simplest way to install the Wolfram Web Engine is by using Docker. A simple Docker image is provided, which is only missing the licensing information to get you started:
docker run -v /path/to/local/folder:/opt/tomcat/webapps/ROOT/active -td wolframresearch/wolframwebengine
Once you have licensed the Wolfram Engine installation in the docker image, you can either use ServiceDeploy or manually edit files in "path/to/local/folder", which is mounted as a Docker volume. Using a Docker volume has the advantage of persisting the web application separately from the rest of the base Wolfram Web Engine image.
Direct Installation
These installation instructions focus on setting up a servlet container and installing the Wolfram Web Engine. As explained previously, the Wolfram Web Engine is based on a standard Java technology called servlets; support for servlets is typically provided by a program called a servlet container. You must set up the servlet container before adding the Wolfram Web Engine.
Installation can take the following steps:
1. Set up a servlet container.
3. Install the Wolfram Web Engine web application into your servlet container.
4. Test your Wolfram Web Engine site.
Setting Up a Servlet Container
Before you start to install the Wolfram Web Engine, 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 here or through a package manager if your operating system supports one. Since Tomcat is a common way to run the Wolfram Web Engine, there is information on installing and setting it up on Linux, Windows and macOS.
The Wolfram Web Engine has been tested with Tomcat. If you have a particular interest or experience in running the Wolfram Web Engine with other servlet 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 the Wolfram Web Engine. If your servlet container does not work, then the Wolfram Web Engine 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 relatively recent version of Java, such as Java SE 17 or later. The appropriate version of Java for your platform can be found here. The Oracle Java site provides detailed installation instructions for the different platforms. However, if your platform has a package manager, you might want to use that to install Java.
You will also need to set the JAVA_HOME environment variable. This is described in the next sections for Linux and Windows.
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 here:
For other shells, you should follow their standards for setting environment variables.
Your JAVA_HOME location might not be the same as the one previously shown. In that case, you will find the path to paste after the equal sign by executing the following command:
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.17.0.14, this is the setting for JAVA_HOME.
Your JAVA_HOME location might not be the same as the one previously shown. In that case, you will find the path to paste after the equal sign by executing the following command:
macOS
macOS Ventura does not ship with Java by default. You can either download it from Oracle's website or get a version via homebrew. Do not forget to set up the JAVA_HOME environment variable properly; this is shown here:
JAVA_HOME=/opt/homebrew/Cellar/openjdk@17/17.0.14/Contents/Home
The default login shell for macOS Ventura is zsh; hence, this command needs to be placed in the appropriate shell initialization file, for example .zshrc.
Your JAVA_HOME location might not be the same as the one previously shown. In that case you will find the paths for all the installed Java versions by executing the following command:
Setting Up Tomcat
This section describes setting up Tomcat on Linux, Windows, and macOS. The main website for Tomcat can be found here.
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. 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 here (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-10.1.39.tar.gz
[server1]$ mv apache-tomcat-10.1.39.tar.gz tomcat
Alternatively, most Linux distributions maintain a Tomcat package. For example, on Debian-based distributions such as Ubuntu, one can install Tomcat by running:
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 Wolfram Engine can store preference 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 following:
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 the Wolfram Web Engine. 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 Linux section.
The bin directory also contains a script, shutdown.sh, used for shutting down Tomcat.
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. 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 the Wolfram Web Engine.
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 the file via 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.
macOS
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.
Download information for Tomcat is available from the Apache website. 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.
Sample shell instructions for these steps are shown here (note that tar xvf 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]$ tar xfz apache-tomcat-10.1.39.tar.gz
[server1]$ sudo mv apache-tomcat-10.1.39 tomcat
Alternatively, one can easily install tomcat using homebrew:
[server1]$ brew install tomcat@10
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:
libexec
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 the Wolfram Web Engine. 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 macOS section.
The bin directory also contains a script, shutdown.sh, used for shutting down Tomcat.
Please also note that for the Wolfram Engine to fully function, you need to log in via the macOS terminal. This is necessary since the Wolfram Engine front end makes use of the macOS windowing environment.
Installing and Configuring Wolfram Engine
Install the version of the Wolfram Engine appropriate for the platform you wish to use for your web server. You should choose a single-machine installation. When you have finished, you should be able to run the Wolfram Engine interactively to validate your installation. If the Wolfram Engine cannot run, then the Wolfram Web Engine cannot run.
If you already have an installation of the Wolfram Engine on your server, you do not need to install the Wolfram Engine again, but can proceed with the remaining installation steps. With an existing installation of the Wolfram Engine, you may place your Wolfram Web Engine license information into a different location, as described in the following section. Placing the license information in a different location will ensure that an interactive usage of the Wolfram Engine on your server does not interfere with the operation of your Wolfram Web Engine site. One possible alternative directory is the WolframWebEngine/WEB-INF/conf directory as demonstrated in the section on installing the Wolfram Web Engine into Tomcat. Note that if you install the license in a special file, you will have to set the -pwfile option when you run the Wolfram Engine outside of the Wolfram Web Engine.
Installing the Wolfram Web Engine Web Application
This section describes how to install the Wolfram Web Engine into your servlet container. For most servlet containers, this involves deploying the Wolfram Web Engine web application found in archived form as a WAR file. Separate installation instructions are given for some different servlet containers. A web application is a collection of HTML and other web components that 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; the WAR file is essentially just a compressed version of that directory structure that gets unpacked automatically by the servlet container.
Tomcat
This section describes the deployment of the Wolfram Web Engine web app in Tomcat. There are two steps: copying the Wolfram Web Engine archive and configuring the WWEConfiguration.xml file.
The Wolfram Web Engine web app is distributed as a WAR file. Copy the archive into the Tomcat webapps directory. This is usually found in the top-level directory of Tomcat. You have now created a web application called the Wolfram Web Engine. Some of the contents of the top directory of Tomcat, along with the location of the web apps directory and Wolfram Web Engine web application, are shown here:
Second, configure the file WWEConfiguration.xml, located in the WEB-INF directory. This file holds various site-specific parameters and may need modification for your site. The settings that can be placed into WWEConfiguration.xml are described in the section on site configuration.
The most important setting is KernelExecutable, the location of the Wolfram Engine kernel. The WWEConfiguration.xml that ships with the Wolfram Web Engine contains settings suitable for a default installation of the Wolfram Engine for Windows, Linux, and macOS. However, if you install the Wolfram Engine into a nondefault location, you will need to modify this file. For example, if you installed the Wolfram Engine into E:\WolframEngine, make the following setting of KernelExecutable in WWEConfiguration.xml:
<KernelExecutable>
E:\Wolfram Engine\MathKernel.exe
</KernelExecutable>
Another reason to modify WWEConfiguration.xml is to store your Wolfram Web Engine license in its own password file, for example WolframWebEngine/WEB-INF/conf/mathpass. It would then be necessary to modify KernelLaunchFlags in WWEConfiguration.xml to ensure that the Wolfram Engine uses this location. The following shows how this can be done for a typical Windows installation:
<KernelLaunchFlags>
-pwfile c:/Program Files/tomcat/webapps/Wolfram Web Engine/WEB-INF/conf/mathpass
</KernelLaunchFlags>
A typical setting for WWEConfiguration.xml to use a special mathpass file under Linux is shown here:
<KernelLaunchFlags>
-pwfile /usr/local/tomcat/webapps/webengine/WEF-INF/conf/mathpass
</KernelLaunchFlags>
If you are interested in deploying Active Web Elements such as APIFunction and FormFunction from a notebook or Wolfram Language script, you will additionally need to create a user in the tomcat-users.xml file. This file is usually located or symlinked in the following location:
In order to set up users you will need to add the user tag below so that it is enclosed in the tomcat-users tag:
<tomcat-users xmlns="http://tomcat.apache.org/xml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
version="1.0">
<user username="deployer" password="changeme" roles="deploy"/>
</tomcat-users>
Change the username and password as appropriate.
Tomcat supports more advanced security options through the configuration of Realms. For example, it is relatively easy to set up a login through an LDAP server. In order to do so, server.xml in the conf folder should contain the following lines:
<Realm
className="org.apache.catalina.realm.JNDIRealm"
connectionURL="ldap://ldap.yourorganization.com"
userPattern="uid={0},ou=people,dc=yourorganization,dc=com"
roleBase="ou=groups,dc=yourorganization,dc=com"
roleName="cn"
/>
In this, the values for connectionURL and various attributes should be set appropriately to your organization.
At the same time, web.xml should be changed appropriately. For example, if one wants to let any logged-in user access a resource regardless of their group, one should set the following:
<auth-constraint>
<role-name>**</role-name>
</auth-constraint>
Through similar techniques, one can define access not just to the ServiceDeploy API endpoint, but to any resource served through Tomcat. The interested user should refer to the Apache Tomcat documentation about Realms or the Java Servlet specification on how to set security constraints in the web.xml configuration file.
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 WWEConfiguration.xml file as described in the section on installing it under Tomcat. It may also be necessary to make various modifications to WWEConfiguration.xml, such as changing the JLinkNativeLibraryDirectory setting. If you wish to deploy Active Web Elements from a notebook or Wolfram Language script, you will need to set appropriate user authentication; for example, in Apache Jetty this is achieved through the jetty-users.properties file.