Jupyterhub with SageMath kernel

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.

Post navigation


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

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

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

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url=""> 

Time limit is exhausted. Please reload the CAPTCHA.