Jupyterhub with SageMath kernel

By behackl,

  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.


  Comments: 10

  1. 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.

    • 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’;
    possibly contact sage-devel (see http://groups.google.com/group/sage-devel).

    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.

      • 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.

          • 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. 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?

    • 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!

    • 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.

Leave a Reply

Time limit is exhausted. Please reload the CAPTCHA.