#+TITLE: Introduction to Yamwi
#+OPTIONS: ^:{} toc:nil num:nil
#+AUTHOR: Leo Butler (based on README_en by Mario Rodríguez Riotorto)
#+MACRO: yamwiurl https://github.com/leo-butler/yamwi/
#+EMAIL: leo.butler@university.ca (university = UManitoba)

* Objectives
*Yamwi* ([[https://github.com/leo-butler/yamwi/][Yet Another Maxima Web Interface]]) is a web interface, based
on Linux+Apache+Php, to the computer algebra system *Maxima*
([[https://maxima.sourceforge.io/]]).

Maxima is the free version (GPL) of the Macsyma system developed in
Lisp at MIT beginning in the late nineteen sixties; other similar
programs (Mathematica, Maple) got inspired by it in the
eighties. Since 2000 Maxima is part of Sourceforge and maintained by
an international team of programers. Due to its advanced routines,
Maxima is also used in research and technical contexts.

Yamwi is of interest in educational contexts, to make interactive
activities with the browser, or to show mathematical concepts. All
sorts of computations and graphics can be made through the web by
Yamwi.

The original author of this software is Mario Rodríguez Riotorto. The
current maintainer is Leo Butler. See [[*Contact][contact information]].

* Screenshot
Here is a screenshot of *Yamwi* with output.

[[file:htdocs/yamwi-in-browser.png]]

* Requirements
The operating system to install Yamwi is Linux.

Software requirements on the server side:

- Apache :: (https://www.apache.org/). (Ver. >= 2).
- Php :: (https://www.php.net/). (Ver. >= 5).
- Gnuplot :: (http://www.gnuplot.info/). This is the program used by Maxima for rendering graphics. (Ver. >= 4.2).
- Maxima :: (https://maxima.sourceforge.io/). This is the mathematical engine. (Ver. >= 5.20).
- timelimit/timeout :: (https://devel.ringlet.net/sysutils/timelimit/ / https://www.gnu.org/software/coreutils/). Bound Maxima's computation time to a fixed limit.

In case the administrator wants to render results in binary TeX
format, the following packages must be also installed (see
configuration variable =$mode= below):

- dvips (from LaTeX)
- texi2dvi (from texinfo)
- convert (from ImageMagick)

* Installation
Once the above-mentioned programs are installed, Yamwi's installation
is as easy as placing the Yamwi's files somewhere accesible to Apache.

Yamwi's source can be downloaded from {{{yamwiurl}}}.

This is the installation process: (requires root privileges)

1. Download the file =yamwi-yy.mm.tar.gz=, where =yy= stands for the
   year and =mm= for the month of release, and place it somewhere
   accesible from Apache. After that, untar it:
   #+begin_src shell :exports code
   tar -xvf yamwi-yy.mm.tar.gz
   #+end_src
   which creates a new folder called =yamwi=.

2. Execute the =INSTALL= script; it sets up directories and files with
   the neccesary permissions. It also creates temporary folder =tmp=,
   where working files will be placed:
   #+begin_src shell :exports code
   sh yamwi/INSTALL
   #+end_src

3. Installation is now complete, in order to play with the demos just
   type the following address in your browser:
   #+begin_src text :exports code
   http://localhost/path_to_folder/yamwi
   #+end_src
   where =path_to_folder= is not necessary if Yamwi was installed in
   Apache's root system.

** A minimal installation
A minimal installation can be achieved by cloning the repository
#+begin_src shell :exports code
  git clone $yamwiurl
#+end_src
Assuming that ~php~ is installed, the following launches Yamwi:
#+header: :var yamwi="."
#+begin_src shell :exports
  cd $yamwi
  mdkir tmp
  php -S localhost:8080
#+end_src

* Configuration
The file =yamwi-conf.php= contains much of the configuration options for Yamwi.

- =$mode= ::  Can be one of 0, 1, 2, 3 or 4. These options are:
  0. [@0] When 0, Yamwi output is rendered in ASCII Art style without any additional processing (in command-line ~maxima~, this is called ~2d~ output);
  1. when 1, results are rendered in binary files containing TeX output (be sure the programs ~texi2dvi~, ~dvips~ and ~convert~ are installed);
  2. when 2, results are rendered in enhanced ASCII-Art style, with syntax highlighting and other features that make it easier to read than mode 0 (in command-line ~maxima~, this is ~2d~ output);
  3. when 3, output is returned as a syntactical Maxima expression (in command-line ~maxima~, this is called ~1d~ output);
  4. when 4, results are based on the nice-looking MathJax (http://www.mathjax.org) system.
  Defaults to 2. Response times are shorter in ASCII Art modes.

- =$max_file_time= ::  Yamwi creates some files which are stored in
  its ~tmp~ folder. Every time a user asks for a calculation, Yamwi
  removes those files older, in minutes, than the quantitity indicated
  by this variable. Defaults to 1.

- =$max_process_time= ::  maximum execution time, in seconds, allowed
  for each Maxima process. Default value is 120 seconds.

- =$max_num_processes= ::  maximum number of Maxima processes
  simultaneously running on the server. Default value is 30.

- =$timelimit_binary= :: Name of the ~timelimit~ binary. Defaults to ~/usr/bin/timeout~.

- =$maxima_binary= :: Name of the ~maxima~ binary. Defaults to ~/usr/bin/maxima~.

- =$maxima_args= :: A string of optional arguments supplied to the ~maxima~ binary. Defaults to ~""~.

- =$magic_key= :: A key that, when passed as part of the URL, causes Yamwi to return diagnostic information along with the normal output. This should be set by the system administrator.

* User Packages
Yamwi gives access to all standard Maxima packages. Custom packages can be placed in the =packages=. The file extension should be =.mac= if the package is written in Maxima code, or =.lisp= if it is written in Common Lisp. Yamwi user can =load=
these packages. See the help file =help_en.html=.

* Security
Take care when using this program. To prevent server damages, some
barriers have been designed:

- There is a list of so called *dangerous words*, which prevents the execution of user code when one of these terms is detected in the input. See the global variable =$dangerous_words=.
- The number of running Maxima processes can be limited. See the configuration variable =$max_num_processes=.
- The execution time of Maxima processes can be limited. See the configuration variable =$max_process_time=.

Even with these filters, Yamwi does not guarantee 100% server
security.

* License
This project is distributed under the terms of the GPL (General Public
License). For more information, read file LICENSE.

* Contact

For bug reports, suggestions or collaboration, feel free to contact me at
[[https://github.com/leo-butler/yamwi/issues]].

* Installing on a VM                                               :noexport:
Let's set up a virtual machine (VM) to run =yamwi= in. I chose Debian,
because that is the Linux distribution that I have used for almost 20
years.

** A VM image
I got the latest debian image, the =sha512= sums, and then did a check:

#+begin_src sh :exports code :eval no-export
  wget https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-nocloud-amd64.qcow2
  wget https://cloud.debian.org/images/cloud/bookworm/20241004-1890/SHA512SUMS
  ln -s debian-12-nocloud-amd64.qcow2 debian-12-nocloud-amd64-20241004-1890.qcow2
  sha512sum -c SHA512SUMS
#+end_src

** A QEMU script
The =qemu= system must be installed. I installed the =qemu-system= package from Debian testing.
I have a script lying around:

#+begin_src sh :tangle ./yamwi-vm.sh :exports code :eval no-export
  #!/bin/bash
  set -aex

  # for monitor info, see https://superuser.com/questions/1087859/how-to-quit-the-qemu-monitor-when-not-using-a-gui

  DISPLAY=:0.0 qemu-system-x86_64 --enable-kvm -m 12G -boot menu=on,splash-time=10000 \
  	    -hda ./debian-12-nocloud-amd64.qcow2 \
  	    -monitor telnet::5557,server,nowait -serial mon:stdio \
  	    -device e1000,netdev=net0 -netdev user,id=net0,hostfwd=tcp::6555-:22,\
  	    hostfwd=tcp::5913-:5913,hostfwd=tcp::9580-:80,hostfwd=tcp::9943-:443 \
  	    -monitor none -vnc 127.0.0.1:11,password=off \
              -virtfs local,path=/etc,mount_tag=host0,security_model=passthrough,id=host0,readonly \
  	    #-runas qemu
#+end_src
