## Jupyterhub with SageMath kernel

##### By behackl, 16th January 2016

Filed under: SageMath
Tags: ,

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.

### Feedback

1. #### salvatore

Generally, you don’t need sudo in front of ./configure and make, because they read user-readable sources and write into user-owned output directories. If you need it, then it’s a bug and you may want to report it upstream. (only) make install should need sudo (when the prefix given to configure is not a user-owned directory, as in this case), because it needs to copy files into system directories.

• #### behackl

Yep, you’re right. No sudo is needed for ./configure and compilation with make, those were just typos. Thanks for your remark!

2. #### Clemens Heuberger

It seems that SageMath 7.4 (at least) requires editing of the kernel.json file to include
 "env": { "SAGE_ROOT": "/opt/SageMath/sage-7.4" }, 
Otherwise, the SageMath kernel is not started with error message

Error: You must set the SAGE_ROOT environment variable or run this
script from the SAGE_ROOT or SAGE_ROOT/local/bin/ directory.
Error setting environment variables by sourcing ‘/opt/SageMath/sage-7.4/local/bin/sage-env’;

This implies that symlinking the kernel directory is no longer sufficient, a copy must be made and the kernel.json file must be edited.

The problem does not occur with SageMath 7.0.

• #### Clemens Heuberger

SageMath 7.5 works fine, just link the kernel directory as described in the post.

• #### Luca De Feo

I am having the same problem with SageMath 8.0. I wonder if this really depends on the version…

• #### Clemens Heuberger

I can no longer reproduce the sucess with SageMath 7.5 without modifying the kernel.json.

• #### Luca De Feo

This does not seem to be specific to jupyterhub. I have the same problem with a system install of jupyter trying to run a Sage kernel.
I’ll check with sage-devel.

3. #### Dima

Do you have an idea how well this setup scales, i.e. how many “light/student” users one can support on one standard desktop box, with something like 8-core i7 CPU and 10-15GB of RAM?

• #### behackl

Unfortunately not the slightest idea. I have only found this: https://github.com/jupyterhub/jupyterhub/issues/505. Extrapolating from the discussion there: if things play out well and if your “light/student” users behave nicely, I could imagine that 25 – 30 users (with about 400-500 MB allocated RAM) should be doable.

But then again, haven’t tried it myself, only (rather optimistic) guessing!

• #### Luca De Feo

Last year I ran the same setup on 8 Xeon X5450 core with 16GB of RAM for 12 students (all students connected simultaneously during classes).

Worked like a charm.