Macaulay2Web - a Web App for Macaulay2

Macaulay2Web is a web interface for the Macaulay2.

It is currently running at https://www.unimelb-macaulay2.cloud.edu.au/.

Quickstart: without virtusalisation

This is now the recommended way, as it is less heavy than with virtualisation. Tools needed: git, nodejs, npm, docker, ssh.

• Run the following from the terminal

git clone https://github.com/pzinn/Macaulay2Web.git
cd Macaulay2Web
npm install
ssh-keygen -b 1024 -f id_rsa -P ''
docker pull pzinn/m2container
docker build -t m2container.
npm run build
npm start docker

• Point your browser to localhost:8002.

Quickstart: with virtualisation

Tools needed: vagrant.

• Run the following commands in a terminal (vagrant might take a while):

git clone https://github.com/pzinn/Macaulay2Web.git
cd Macaulay2Web/setups/basic
vagrant up

• Point your browser to localhost:8002.

Macaulay2Web

Macaulay2Web has a server/client structure, with the client running in the browser, and the server transmitting Macaulay2 input sent by the client to a Macaulay2 process that it creates for each user. The Macaulay2 process runs in a special mode (WebApp mode) which allows for output to be typeset using KaTeX/HTML rather than the default text output.

InteractiveShell

Macaulay2Web is based on InteractiveShell, a terminal emulator giving you an interface to a Macaulay2 instance running remotely. The main advantage of providing a web app rather than a native app is that you do not need to download and install Macaulay2, thus easing the entry barrier for new users. We have also found that users unfamiliar with unix-style command-line tools are more comfortable using a web app than a terminal.

The interface

The web app contains interactive tutorials that explain how to use the web app, show some more advanced features of the app, e.g., retrieving files generated by Macaulay2, and teach basic and advanced algebraic geometry. You can create your own tutorials. If you teach a course, email your tutorial to your students, they can then click Load Tutorial on the website and work through the tutorial. If you want to share tutorials with the community, we would be happy to include them on the website!

When you write functions or whole packages, you will probably want to use the Editor area on the left: edit your Macaulay2 code on the left as if it were a text editor. At any time, you can run your code by clicking Evaluate. Evaluate either evaluates the current line or any code selected. This is inspired by traditional Macaulay2 usage, which has been designed to work with Emacs where a plugin allows you to run code from within the editor.

The interface contains two more tabs: a chat tab which allows for simple interaction with users and messaging from the system; and a browse tab, mostly used for documentation (though it can in principle display any URL).

Usage

Macaulay2Web works from any device, even mobile, all you need is a network connection. A new Macaulay2 instance is started for every user and provides them with an underlying linux system of their own. Thus you can use all the features of a natively installed Macaulay2 such as executing linux commands through Macaulay2's get command, accessing the file system to write and read files, and installing third party Macaulay2 packages.

Users are identified by cookies. If you run long computations, you can come back later and the results will be ready for you. There are mechanism to restrict ressources allocated to each user.

Installation

Without virtualisation

If you do not want to run the web app within a virtual machine, you can run it locally. You need Node.js, npm, and Git. Furthermore you need to have a local ssh server running. Try whether the following command works without prompting you for a password:

ssh -i ~/.ssh/id_rsa localhost

If not, please start an ssh server and include you public key in your authorized keys file.

There are two options:

With docker containers

The server will run locally, but the Macaulay2 processes will be spawned in docker containers.

• Go to https://github.com/pzinn/Macaulay2Web and clone the appropriate branch (main = HTTP, https = HTTPS), say

git clone https://github.com/pzinn/Macaulay2Web.git

• Inside the Macaulay2Web directory (e.g., cd ~/Macaulay2Web first), run

npm install

(which should also run the postinstall script)

• Set up the ssh stuff:

ssh-keygen -b 1024 -f id_rsa -P ''

• Run

docker pull pzinn/m2container

(this downloads a docker container with Macaulay2)

• Run

docker build -t m2container.

inside the Macaulay2Web directory: this creates a local version of the docker container.

• (optional) Set an admin id in src/server/defaultOptions.ts:

adminName: "adminsecretid999", // to be set live only

• Build everything:

npm run build

• Start the server:

npm start docker > macaulay2web.log

(the log file is optional, obviously)

• Then open a browser at http://localhost:8002.

Without docker containers

If you do not want to use docker containers, you also need Macaulay2 installed locally. Start the web app with the following commands:

git clone https://github.com/pzinn/Macaulay2Web.git
cd Macaulay2Web
npm install
npm run local

This gives you an (unsecured!) Macaulay2 terminal emulator at http://localhost:8002. That means users can access and modify your private data through Macaulay2's get command. Make sure you do not allow web access to your machine to other users on the same network, i.e., make sure your laptop's firewall is on. The port may be different, check the console output where you started the server for Server running on [port].

With virtualization

We have a Vagrant file that configures a virtual machine with everything you need to run your own Server with Macaulay2. You do not need to install Macaulay2 locally.

Make sure VirtualBox and Vagrant are installed. On Windows, we recommend to run Vagrant from within Git BASH. Do the following inside a terminal or Git BASH:

git clone https://github.com/pzinn/Macaulay2Web.git
cd Macaulay2Web/setups/basic
vagrant up

The web app is running at http://localhost:8002. Every Macaulay2 instance runs in a separate Docker container with limited resources and does not have access to your filesystem. Users can only access files inside their Docker container. You can manipulate the memory limits of the server in the Vagrantfile and for the single users in the file {Macaulay2Web/src/server/startupConfigs/default.ts}.

If vagrant cannot mount due to a vboxfs not found error, do

vagrant plugin install vagrant-vbguest

HTTPS

Macaulay2Web has another branch, https, which allows for communication to the server via the HTTPS protocol. Currently the vagrant set-up does not use this branch. To have HTTPS, follow the same instructions as above (with no virtualization), except add after cloning:

git checkout https

Additional set-up is needed in order to have a valid HTTPS server; Macaulay2Web's https branch uses greenlock for that.

Scaling Up (Advanced)

With Vagrant it is easy to run the web app in the cloud, e.g., at AWS or DigitalOcean. You need to customize the file Vagrantfile_aws with your credentials.

When you teach large classes, the resources on one machine might not suffice. Remember, for every user we start a Docker container with Macaulay2. The Docker containers and the server that handles requests can be on remote machines because they communicate via ssh. We have a vagrant configuration that starts server and containers on separate instances.

cd separate_machines
vagrant up

Adjusting resource limits

You can manipulate the resource limits of the virtual machine in the Vagrantfile. Furthermore the file

Macaulay2Web/src/server/defaultOptions.ts

contains several default values for the ressource limits of the single container.

Linting

We use Eslint

npm run lint

Running the server

We recommend developing locally and running

vagrant up developer

In this setup, the source code is symlinked between your host and guest system. Allowing you to develop locally but having the complete setup with Docker and separate virtual machines for server and Docker containers. To start different versions run

npm run local  ## insecure -  without Docker containers
npm start ## basic with Docker containers
npm run twoMachines ## Docker containers on different machine than server

Command line arguments:

You can append to the URL, say http://localhost:8002 or https://www.unimelb-macaulay2.cloud.edu.au the following:

• #[home|tutorial|editor|about|browse] to start in a different tab (in the normal interface). #tutorial-name-n to go to page n of tutorial name.
• ?user[=name] to choose one's own user id. This allows e.g. to have the same session on different computers or share one's session with someone else. Note that if you have already been assigned a user id, this will overwrite it (i.e., it will overwrite the cookie containing it), so use with caution (if you don't know your previous user id, you will lose access to your previous session). At the moment, the only way to know your current user id is to click on the word "cookie" on the home page, or look at the log in the chat tab.
• /minimal.html for a minimal interface, which can be embedded into a web page, e.g. with

<iframe style="background:#A8A8B8;overflow:hidden;resize:both" scrolling="no" src='https://www.unimelb-macaulay2.cloud.edu.au/minimal.html' title="Macaulay2"></iframe>

The minimal interface does not read/write cookies; if no user option is specified, it uses a default "public" id (i.e., the session is shared by all users).

Internal file structure:

Server

• main file: dist/server/index.js produced by tsc:

npx tsc

(or ./node_modules/.bin/tsc) from src/server/index.ts

• other files: dist/server/*.js dist/startupConfigs/*.js dist/common/*.js from src/server/*.ts src/startupConfigs/*.ts src/common/*.ts

Client

• main file: public/index.js produced by webpack from src/client/*.ts and src/common/*.ts using ts-loader and called by public/index.html.
• minimal version is the same with index -> minimal.
• alternatively one can transpile first using

npx tsc -p src/client