#+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).
- 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.

** Recommended
Yamwi can be extended by installing the following software:

- Gnuplot :: (https://www.gnuplot.info/). This is the program used by Maxima for rendering graphics. (Ver. >= 4.2).
- FFmpeg :: (https://ffmpeg.org/). This program is used with ~Gnuplot~ by Maxima to create animations. (Ver. >= 5.0).

To enable ~Gnuplot~ (respectively, ~Gnuplot+FFmpeg~) is simple: the
administrator sets ~$gnuplot_binary~ to the pathname of the ~gnuplot~
program (respectively, sets both ~$gnuplot_binary~ and
~$ffmpeg_binary~ to point to the relevant programs). If Yamwi cannot
find ~gnuplot~, all plotting is disabled; if it cannot find ~ffmpeg~,
animations are disabled.

* 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
  mkdir 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, output is returned as a syntactical Maxima expression (in command-line ~maxima~, this is called ~1d~ output);
  1. when 1, Yamwi output is rendered in ASCII-Art style without any additional processing (in command-line ~maxima~, this is called ~2d~ output);
  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, results are rendered using Maxima's =MathML= processor;
  4. when 4, results are based on the nice-looking MathJax (http://www.mathjax.org) system.
  Defaults to 2. The user may select the mode.

- ~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 ~""~.

- ~gnuplot_binary~ :: Name of the ~gnuplot~ binary. Defaults to ~/usr/bin/gnuplot~.

- ~gnuplot_args~ :: A string of optional arguments supplied to the ~gnuplot~ 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.

- ~$movie_muxer~ :: The name of the container used by ~ffmpeg~ to produce a video, shown in a =<video>= element. Must by either =webm= or =mp4=. Defaults to =webm=.

- ~$movie_is_embedded~ :: If ~1~, the video made by ~ffmpeg~ is base-64 encoded and embedded in HTML; otherwise, the video is saved to file and the file-name is embedded in HTML.

- ~$ffmpeg_binary~ :: The name of the ~ffmpeg~ binary. Defaults to ~/usr/bin/ffmpeg~.

- ~$base64_cmd~ :: The command used to encode images and videos to base-64 encoding. Defaults to ~/usr/bin/base64 -w 0~.

* 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
