Jupyterhub with SageMath kernel

By behackl,

Recently I made some efforts to get a Jupyterhub instance with a SageMath kernel up and running on one of my servers — with success! 🙂 Actually, the installation is really not that difficult. Nevertheless, I want to write a few lines describing the troubles I ran into and my solutions.

Installing Dependencies

The dependencies of Jupyterhub are well-explained on their github page, and their installation should not result in big trouble. However, as my server runs CentOS 7.2, I had to compile a recent Python version by myself:

Then, in order to find the library, you have to add the line /usr/local/lib to /etc/ld.so.conf.d/local.conf and reload the config by calling ldconfig. These steps (usually) have to be completed as root. Afterwards, Python 3.5.1 should be installed (you can check with python3.5 -V or pip3.5 -V).

The goal of these steps was to obtain a useable installation of pip.

The installation of the second dependency, the node package manager “npm” was straightforward:

Installation of Jupyterhub and linking the SageMath kernel

The next part is really easy: Jupyterhub (together with the notebook) can be installed with the help of pip just by calling

The available kernels then can be listed with jupyter-kernelspec:

In order to add a SageMath-kernel to your installation, you first need a working Sage install. For example, I’ve installed sage-6.10 in the /opt-directory, so that I can run Sage by calling

Then, all that needs to be done is linking the kernel into a directory, where Jupyter is aware of them:

After linking the kernel, jupyter-kernelspec list should already list the new kernel like this:

Configuring the Webserver

In my case, I configured Jupyterhub to run behind a reverse proxy, powered by an Apache web server, such that the service can be reached from a subdomain like https://jupyter.example.com.

First, note that Jupyterhub can be started just by using the command jupyterhub. With jupyterhub --port 98765, you can run the serivce at localhost:98765. The complicated part with the Apache configuration is that you also have to take care of the websockets — otherwise the kernels are not able to connect. The following snippet comes from my Apache configuration:

And finally, in order to have Jupyterhub in a systemd-setting, I’ve put the following into /usr/lib/systemd/system/jupyterhub.service:

… and that’s it! The service can then be started by reloading the configuration via sudo systemctl daemon-reload and sudo systemctl start jupyterhub.service.