This repository illustrates Binder use cases for SageMath.

This repository provides some simple live demos for SageMath and other software included in the SageMath distribution.

• index.ipynb: starter notebook / brief SageMath demo
• demo-gap.ipynb: brief GAP demo
• demo-pari.ipynb: brief Pari/GP demo
• demo-singular.ipynb: brief Singular demo

Have a repository full of Jupyter notebooks using SageMath? It's easy to setup Binder to let anyone run them. Just copy the short Dockerfile from this repository, and adapt it to your needs. You probably also want to insert the Binder badge in your READ ME.

Examples: - Some live slides for a talk - A research paper logbook

Have HTML pages (e.g. documentation) containing chunks of SageMath code? With Thebe, it's easy to turn them into live code cells that will use Binder and the executable environment defined by this repository.

See this Thebe example.

For the Sphinx-generated documentation of a Sage based project, you can use the Sphinx extension provided by the Sage package authoring utilities. For an example, see this demo page, and click Activate.

Note: Thebe is similar in principle to SageMath Cell. It introduces additional flexibility by enabling the customization of the programming language (kernel), computing backend (e.g. local Jupyter server, ...) and executable environment (e.g. via Binder). It also targets a much broader community, with the potential to relieve the SageMath community from maintaining a custom solution. On the other hand it's still relatively recent and quickly evolving technology with less settled sustainability. Also the SageMath Cell has been optimized to be more reactive on startup and reduceapt resource consumption. Those optimizations have not yet been ported to Thebe+binder.

See also thebe.rst for additional reader-oriented notes.

The sample Dockerfile in this repository is based on the official sagemath/sagemath Docker image. It includes Sage itself, and all the software packages typically included in a standard Sage installation, though not everything (in particular not optional Sage SPKGs, or other system software packages).

So in order to install additional Sage SPKGs it is possible to include a line like:

RUN sage -i <spkg-name>

in the Dockerfile. Note, due to a current shortcoming in the official Docker image it is also necessary to install the make system package before running sage -i. See the next section.

To add additional software packages a couple more steps are involved, albeit relatively simple. The thing to understand about the sagemath/sagemath image is that by default it puts you in a user called sage, so in order to install system packages it is necessary, when extending the image, to first switch back to the root user. Then, because the image is based on Ubuntu, the apt-get command can be used to install Ubuntu packages. The canonical way to do this in a Dockerfile involves updating the APT cache, installing the packages, and then cleaning up the APT cache again all within a single command (this is in order to keep cache files out of the image):

USER root
RUN apt-get -qq update \
 && apt-get -qq install -y --no-install-recommends <packages-to-install> \
 && apt-get -qq clean
USER sage

Finally, just make sure toward the end of the Dockerfile that you switch the image user back to sage (so that when users run the container they are not running it as root.

Nicolas M. Thiéry E. Madison Bray

The demo notebooks for GAP, Singular, and Pari were written by the authors of the respective kernels. See the report on their implementation.

Contributions most welcome!