SingularWS
==========

1. About
--------

This simple webservice is created for mathematics software that requires
outsourced computations, mainly in ideal theory and commutative algebra.

To install it, you need an Apache server with PHP enabled, and Singular
must also be installed and available on the command path. The most
convenient way is to set up a Debian/Ubuntu server and install
the following pieces of software:

* libapache2-mod-php5
* singular

Then copy all files into /var/www as root and chmod 1777 /var/www/cache.

This software is intended to run on a standalone machine, preferably
on a virtual host.

Author: Zoltan Kovacs <zoltan@geogebra.org>
License: GPL3


2. Hints for production use
---------------------------

Since requests can be the same for different uses in many situations
(e.g. classroom use with several users, repetition of a set of
problems), it is considerable to use the internal caching mechanism. In
former versions of this documentation mod_cache, mod_disk_cache modules
of Apache, or the Varnish accelerator were suggested. Now we encourage
to use the internal caching in SingularWS (based on SHA1 hashes)
instead.

2.1. Downloading a virtual machine
----------------------------------

Many people just want to use SingularWS, but not to play with the
installation and configuration details. To ease their life, the GeoGebra
Team provides a VirtualBox virtual appliance to download at
http://ggb1.idm.jku.at/~kovzol/server.html. After downloading it (that
is a zipped .vdi file), please start VirtualBox and load the appliance
file, then start the virtual machine. You can learn more on this here:
http://hacktolive.org/wiki/Using_VirtualBox_images_(.vdi_files) --- for
OS you could select Linux, Ubuntu (64 bit), the suggested memory is at
least 1 GB (for the very start 512 MB is also enough). Before starting
the machine it is important to change the network settings. You may
certainly want to enable the network interface to a bridged card to make
it possible for other machines to reach SingularWS from your local
network (intranet).

It is suggested to change the password for the singularws user (password
is the same as the username) when logging in at the first time. Remote
SSH login is also available. An experienced system administrator may
want to add extra safety by setting up a sophisticated firewall, for
example.

It is crucial to find out the IP address of your freshly started virtual
machine. After logging in, this can be achieved by running the
"ifconfig" command. (Another possibility is to check the network traffic
log on your router, if it is capable of this.) Then you can point your
browser to the IP of the virtual machine, e.g.:

http://192.168.1.102

Such a request should return the "e1" output (which means error code 1:
no command defined or no such command).

Please note that the virtual machine will be automatically set to obtain
a DHCP address from the same network as the host machine obtains its own
IP address from. To change or fine tune this behavior please consult the
VirtualBox documentation, the handbook of your router, and/or your
network administrator.

A demo virtual server can (hopefully) always be available at the
following URL:

http://singularws.idm.jku.at

2.2. Creating a virtual machine
-------------------------------

We assume that you use a modern Linux workstation for your work.

a) Download Ubuntu Server from http://www.ubuntu.com/download/server
   in an ISO file. The 64 bit version will be fine.

b) Install and run VirtualBox.

c) Click New -> Next. Fill in the form: Name: SingularWS, OS Type:
   Linux, Ubuntu (64 bit). Set the base memory size to 1024 MB.

d) Set up a VDI type virtual disk with dynamically allocated size,
   2000 MB should be enough.

e) Start the machine, and select the Ubuntu Server 64 bit ISO file
   for installation media. Install Ubuntu by using the default
   settings everywhere, except for host and user names and
   passwords (everywhere "singularws"), and that for partitioning
   "Manual" should be used (enabling the whole space to a single
   partition into /dev/sda1, no swap space is needed), and the
   OpenSSH server will be installed as a basic service.

f) After the first reboot, log in and ask the IP address of the machine
   by running "ifconfig". Then add new port forwarding rules to VirtualBox
   in the Network section:

   - protocol TCP host 127.0.0.1 port 2222 to guest 10.0.2.15 port 22
   - protocol TCP host 127.0.0.1 port 8080 to guest 10.0.2.15 port 80

   (Here you must change 10.0.2.15 to your IP address of the new machine.)

g) Log in to the new machine from your workstation by doing the following:

   $ ssh -p2222 singularws@127.0.0.1

   After a successful login:

   $ sudo su

   Here type the password (singularws), and then:

   # apt-get install libapache2-mod-php5 git

   Now follow the steps at http://www.singular.uni-kl.de/index.php/singular-download/110.html
   (just copy-paste the commands).

   You should install extra Singular packages at this point. So enter

   # cd /usr/share/Singular/LIB
   # wget -N http://webs.uvigo.es/fbotana/grobcovG.lib

   Then:

   # cd /var
   # git clone https://github.com/kovzol/singularws.git
   # mv www www.orig
   # ln -s singularws/ www
   # cd www
   # mkdir cache
   # chmod 1777 cache

h) Now you can try if SingularWS is working properly by using the following links
   on your workstation:

   http://127.0.0.1:8080
   http://127.0.0.1:8080/?c=s&p=12345*54321;

i) Ensure that the cache will be deleted regularly by starting "crontab -e",
   and adding the following line (first you may have to choose an editor):

     0 7 * * * cd /var/www/cache; find . -ctime +3 -maxdepth 1 | xargs rm -fR

   and save the file.

j) Updating Linux packages, and cleaning, also shrinking the .vdi file:

   # apt-get update; apt-get upgrade
   # apt-get autoremove; apt-get clean
   # cd /var/www/cache; find . -maxdepth 1 | xargs rm -fR
   # cd /tmp; find . -maxdepth 1 | xargs rm -fR
   # rm /etc/udev/rules.d/70-persistent-net.rules
   # rm /home/singularws/*Singular*
   # cd /var/log; find . -maxdepth 1 -not -name apache2 | xargs rm -fR
   # dd if=/dev/zero of=/bigemptyfile bs=4096k
   # rm /bigemptyfile
   # rm ~/.bash_history; exit
   $ rm ~/.bash_history; exit

k) Now switch off the SingularWS virtual appliance (also possible via command
   line in your workstation by entering "VBoxManage controlvm SingularWS poweroff").

l) The .vdi file for the appliance will be put into

   /$HOME/VirtualBox\ VMs/SingularWS/SingularWS.vdi

   So, if you want to create a .zip file of the .vdi, you should enter the following:

   $ cd $HOME/Virtual\ VMs/SingularWS
   $ zip SingularWS.zip SingularWS.vdi

   Of course you may use a different name for the .zip file to distinguish
   between different versions.

2.3. Updating a virtual machine
-------------------------------

Follow steps a)-c) from 2.2. first, then:

d) In the Virtual Hard Disk choose "Use existing hard disk" and open the .vdi file
   you want to update. Create the appliance.

e) Log in as singularws, then do the following:

   $ sudo su
   # cd /var/www
   # git pull

f) Finally, do the same as in 2.2. j)-l).


3. Using SingularWS
-------------------

SingularWS can be used via its application programming interface (API)
which is defined in inc/commands.php. Basically, the most typical use
is to send the calculation request via an HTTP URL by setting the GET
parameters as needed.

Here are some simple examples:

* http://singularws.idm.jku.at/?c=t
* http://singularws.idm.jku.at/?c=s&p=12345*54321;
* http://singularws.idm.jku.at/?c=s&p=123-45;67%2B8;
* http://singularws.idm.jku.at/?c=s&p=ring%20r=0,(x,y),dp;ideal%20I=x^2,x;groebner(I);
* http://singularws.idm.jku.at/?c=s&p=12345*54321;&l=1

The first example is a simple connection test, it should return "ok".
The second one simply multiplies two numbers---note the semicolon at the
end to ensure a nice output ("670592745 >", here the "greater than" sign
is the Singular prompt). The third one is a substraction and an
addition---note that "%2B" must be used instead of "+" (since "+" is
always converted to a space character). If you plan to use SingularWS
from a computer program you write, consider using an URL encoder
subroutine (e.g. urlencode in PHP, encodeURL in Java or quote_plus
in Python's urllib).

The fourth example shows the programming capabilities of Singular. It
calculates the Groebner basis of an ideal which consists of the
polynomials x^2 and x. (In any URL the space character can also be used,
but after serving the request, the web browser usually converts all
spaces into "%20" strings. Here in the example we used "%20" as an
input, too, for emphasizing that the URL is one text, not two ones.) The
calculation is done in R[x,y], and the ordering is "dp" which stands for
the reversed graduated lexicographical ordering. For more details please
consult the Singular documentation.

The fifth example shows how to set the internal caching on. SingularWS,
by default, does not do any caching for backward compatibility. The
setting "l=1" instructs SingularWS to use the cache lookup table first
when preparing for the computation. "l=0" forces not to use the cache.

By default, calculation limit is set to the timeout of 30 seconds.
This can be fine tuned in inc/conf.php. Raspberry Pi users may want to
change the $SILENT variable in the same file, too.

SingularWS can also work with POST requests: this is recommended for
sending bigger computations. For GET requests, a length limit for the
command should be expected on both client and server sides. E.g.
Internet Explorer users will be unable to send Singular program codes
longer than about 2000 bytes embedded in the URL, but other browsers
will also stop working yet below 10000 bytes. On the other hand, the
default Apache configuration for the LimitRequestFields and
LimitRequestFieldsize directives are set to 8190 during compilation
time. This means Apache also has to be recompiled with an increased
setting for long GET requests.

3.1. The SingularWS API
-----------------------

In the present state of SingularWS just a very limited set of commands
are available, namely:

* c=t (command: connection test)
* c=s (command: Singular direct call) p=... [l=...]

In the future some other commands may be added.

3.2 Example use in GeoGebra
---------------------------

At the moment this is in experimental state, but one can find the
current source code at
http://dev.geogebra.org/trac/browser/trunk/geogebra/common/src/geogebra/common/cas/singularws/SingularWebService.java.


4. Official webpage and news
----------------------------

Please check http://ggb1.idm.jku.at/~kovzol/server.html for the newest
version of this software.


5. Acknowledgements
-------------------

Creating SingularWS was motivated by Francisco Botana and his automated
theorem proving subsytem, written for Sage and GeoGebra. He himself did
some testing on SingularWS.

The author of this package thanks for the support of The GeoGebra Team,
lead by Markus Hohenwarter. The testing and web site architecture is
also supported by the Department of Mathematics Education, Johannes
Kepler University, Linz, Austria.

The automated theorem proving project for GeoGebra is advised by Tomas
Recio. His and Botana's work was partially supported by grants
MTM2008-M04699-C03-03 and MTM2011-25816-C02-02.