This project, originally developed at the Mathematical Institute of Goettingen, provides an alternative CAS server implementation for stack, which is a question type for ilias and moodle focused on math. The image was originally developed to be used in a cluster/loadbalancing setup, but for most workloads it is viable to use it as a single container.
This implementation in golang strives to have faster startup and processing times than the corresponding java version by using fork instead of starting a new process for each request. For some more information on how this works, see the documentation.
The prebuilt docker images are available from the docker hub at mathinstitut/goemaxima:[version]-latest.
To use it, you first have to know what stackmaxima version you need. Note that this is different from the moodle stack version, ilias stack version and maxima version. The needed stackmaxima version can be seen in the "What Stackmaxima version do I need?" section.
They can be simply run with docker compose in the top-directory of the repository (setting the STACKMAXIMA_VERSION to the desired value):
echo STACKMAXIMA_VERSION=2024111900 > stackmaxima-version
docker compose --env-file=stackmaxima-version up -d
The container should then be available on port 8080 (from outside the host too, keep this behind a firewall so it is not reachable from the general internet).
The port of the server inside the container is 8080 and the path that has to be input into stack is http://[address:port]/goemaxima.
Some older versions of the image accept only http://[address:port]/maxima and this url should work in newer versions as well.
Stack expects a maxima version to be set in the settings.
You can find out which maxima version to use for a particular STACKMAXIMA_VERSION by taking a look at the last column in the "What Stackmaxima version do I need?" section
If you do not wish to use the docker-compose configuration, you can also run the image with
$ docker run --restart=always --tmpfs /tmp -p $address:$port:8080 $imagename
where $address:$port is the ip and port you want to make the service available on and $imagename is the name of the docker image you chose (e.g. mathinstitut/goemaxima:2020120600-latest).
Use 0.0.0.0 as address to listen to all addresses.
Note that this program prefers to quit on errors it can not recover from, so setting restart=always is strongly recommended.
The memory usage of the container is around 50MB when idle and can quickly spike to 250MB on heavy use. The process startup time for a single request is a few milliseconds and negligible in comparison to processing the CAS request itself.
For advanced users, one can also deploy the image in kubernetes by using the helm chart provided in the helmmaxima directory.
| Ilias Stack Version | Moodle Stack Version | Stackmaxima version | Included Maxima version |
|---|---|---|---|
6, 7 |
4.2.2a |
2019090200 | 5.41.0 |
| - | 4.3.1 |
2020042000 | 5.41.0 |
| - | 4.3.2 |
2020052700 | 5.41.0 |
| - | 4.3.3 |
2020061000 | 5.41.0 |
| - | 4.3.4 |
2020070100 | 5.41.0 |
| - | 4.3.6 |
2020100900 | 5.41.0 |
| - | 4.3.7 |
2020101501 | 5.41.0 |
| - | 4.3.8 |
2020120600 | 5.41.0 |
7-DEV |
4.3.10 |
2021120900 | 5.44.0 |
| - | 4.3.11 |
2022060100 | 5.44.0 |
| - | 4.4.0 |
2022071300 | 5.44.0 |
| - | 4.4.1 |
2022082900 | 5.44.0 |
| - | 4.4.2 |
2023010400 | 5.44.0 |
| - | 4.4.3 |
2023052400 | 5.44.0 |
| - | 4.4.4 |
2023060500 | 5.44.0 |
| - | 4.4.5 |
2023072101 | 5.44.0 |
| - | 4.4.6 |
2023102700 | 5.44.0 |
7.5, 8.5 |
4.5.0 |
2023121100 | 5.44.0 |
| - | 4.5.0-hf2 |
2024012900 | 5.44.0 |
| - | 4.6.0 |
2024060300 | 5.44.0 |
| - | 4.7.0 |
2024072400 | 5.44.0 |
| - | 4.8.0 |
2024111500 | 5.44.0 |
| - | 4.8.1 |
2024111900 | 5.44.0 |
There are prebuilt images are already available on the dockerhub. This section just describes the build process in case you want to build your own image anyway. Normally, you can just skip this step and go to Using the Docker Image directly.
The docker container for a particular stackmaxima version can be built by invoking buildimage.sh STACKMAXIMA_VERSION with STACKMAXIMA_VERSION being the stackmaxima version to base the container off.
Example:
$ ./buildimage.sh 2020061000
The image should then be available as goemaxima:2020061000-dev.
The supported stackmaxima versions can be seen by looking at the versions file of the root of this repository.
A few internal options can be set from environment variables.
-
GOEMAXIMA_DEBUGactivates some debug logs withGOEMAXIMA_DEBUG=1(or more withGOEMAXIMA_DEBUG=2). -
GOEMAXIMA_EXTRA_PACKAGESis a colon-separated list of maxima packages that gets loaded at startup at the server. The load time of the packages mostly influences the startup time of the server itself and should not significantly affect the serve time of a request. The entries simply get loaded through a load(entry) call in maxima. This means you can also mount your own maxima libraries into the docker image and load them by using a path. -
GOEMAXIMA_NUSERsets the number of processes that can run at the same time. The maximum number is 32 and it is the default. -
GOEMAXIMA_QUEUE_LENsets the target number of processes that are idle and ready to accept a request. The default is 3 (but note that there is always one extra process waiting). -
GOEMAXIMA_TEMP_DIRis the temporary directory where maxima processes write plots and have their named pipes. Its default is/tmp/maxima. It is the only location where the server writes to and should be mapped to tmpfs to increase speed. -
GOEMAXIMA_LIB_PATHis the path to a library that is loaded on startup of the maxima process. If you do not modify the container or use the webserver executable in another context than the image, you probably want to leave this variable unset. If you want to load extra packages/libraries, use theGOEMAXIMA_EXTRA_PACKAGESvariable instead. -
GOEMAXIMA_PROCESS_ISOLATIONis eithernoneornormal. Ifnormal(the default), the maxima processes are run under separate users to prevent them from interfering with each other. As a consequence of this, the server needs to be the root user (so thatCAP_SETUID/CAP_SETGIDare available). However, in the case ofnone, the processes all run as the same user and the server must not run as root. This is useful in environments where the root user is not allowed, however it does mean that, in case of a hijacked process, the attacker can also hijack the server process.
Prometheus metrics are published on /metrics and include number of success, timeout and internal error responses and also histograms of process startup and response times.
goemaxima is licensed under the GPLv3.