Setup your home JupyterHub on a Raspberry Pi

Start a notebook from any device in your house. One hub for the whole family.

Published in

Towards Data Science

5 min readMay 2, 2020

As a data scientist, I use Jupyter notebooks on a daily basis. Sometimes locally on my notebook, sometimes on a server through JupyterHub. But why not combine both and run a JupyterHub on a Raspberry Pi? This way everyone in the household can start a notebook from every device with a browser. The data always stays home and as Raspberry Pis become more and more powerful, we can actually do real data science on it.

A little bit of Machine Learning on my tablet. Next to it: Raspberry Pi and coffee.

Prepare Python environment
Install JupyterHub
Set up as a system service
Use JupyterLab
Install Python Libraries
User Management

Prepare Python environment

There are many articles out there that describe how to set up JupyterHub, most of them, however, use Anaconda. Unfortunately, Anaconda does not support ARM-systems like the Raspberry Pi and Miniconda, that is often suggested as an alternative, is apparently not further maintained. So let’s go with pip.

Did I do something wrong? When I typed “python” in my fresh Raspbian Buster installation, it opened “python2”. Seriously? Isn’t it 2020? So let’s quickly redirect the system to python3:

sudo rm /usr/bin/python 
sudo ln -s /usr/bin/python3 /usr/bin/python

and install the python package manager pip:

sudo apt-get update 
sudo apt-get install python3-pip 
sudo pip3 install --upgrade pip

Install JupyterHub

JupyterHub consists of three components:

A single-user notebook server that is started for every user on the system when they log in. This is basically what you have installed on your laptop and start with jupyter notebook.
The hub that manages the user accounts, authentication and coordinates the single-user notebook servers.
A proxy that routes the user requests to the hub and the notebook servers.

Accordingly, we need to install these three components. Let’s start with the proxy:

sudo apt-get install npm 
sudo npm install -g configurable-http-proxy

Now, we can install JupyterHub and Jupyter Notebook using pip. Since we want to use JupyterHub for multiple users, we need to make sure that the installation is system-wide:

sudo -H pip3 install notebook jupyterhub

JupyterHub is configured using a python script. You can generate the template using the following command. Afterwards, move it to a location outside your home directory:

jupyterhub --generate-config 
sudo mv jupyterhub_config.py /root

In the following steps, when we make changes in the config file, we need to modify this file /root/jupyterhub_config.py. Since it is located in /root, we need to use sudo.

For example, by default JupyterHub runs on port 8000. Maybe we already have this port in use, so let’s change it to 8888. For that uncomment the following statement in the config-file and adjust the port:

c.JupyterHub.bind_url = 'http://:8888'

Set up as a system service

Our JupyterHub is now ready to go. We could start it with jupyterhub -f /root/jupyterhub_config.py & (where -f points to the config file we just created). However, the hub would only survive until the next restart of the system. Fine for a first try but if we use it on a regular basis, it is certainly better to set up JupyterHub as a system service so that it is automatically launched at system start.

To register JupyterHub as a system service, create the file /lib/systemd/system/jupyterhub.service and fill it with:

[Unit] 
Description=JupyterHub Service 
After=multi-user.target  [Service] 
User=root 
ExecStart=/usr/local/bin/jupyterhub --config=/root/jupyterhub_config.py 
Restart=on-failure  [Install] 
WantedBy=multi-user.target

Make sure that the line starting with ExecStart contains the correct location of the JupyterHub binary and the config-file or adjust accordingly.

Afterwards, run the following commands:

sudo systemctl daemon-reload 
sudo systemctl start jupyterhub 
sudo systemctl enable jupyterhub 
sudo systemctl status jupyterhub.service

JupyterHub will now launch at system start. The last command shows you the status which is hopefully “active (running)”.

If this is the case, go to http://<address of your raspi>:8888. You should see the login page of your JupyterHub. Every system user of the Raspberry Pi can now log in and launch their own notebook server!

Use JupyterLab

JupyterLab is the next-generation web-based user interface for Project Jupyter. It allows you to work with documents and notebooks in a very flexible manner. If you are not convinced yet: It even has a dark mode…

To use JupyterLab instead of the traditional notebooks, we first have to install it using pip and then enable the extension (use sudo to do it systemwide):

sudo -H pip3 install jupyterlab  
sudo jupyter serverextension enable --py jupyterlab --system

Now, we have to add (or uncomment and adjust the respective line) the following in the config-file:

c.Spawner.default_url = '/user/:username/lab'

Install Python libraries

To do actual data science, we will certainly need a bit more than just the python standard library. We have essentially two possibilities: We can install them system-wide. Alternatively, every user can install them in their home directory.

A reasonable approach would be to install the most often used packages system-wide and let the users install everything else on their own. As an example here is how to install numpy system-wide. For numpy to work, you will also have to install the following system package:

sudo apt-get install libatlas-base-dev 
sudo -H pip3 install numpy

Users without sudo-rights can install packages in their home directory with, for example:

pip3 install seaborn

You can actually open a terminal from within JupyterLab, so there is no need to set up a ssh-connection for “normal” users. Just go to the launcher window and open a terminal.

First open the Launcher window. From there, you can open a new notebook or terminal.

User Management

In our current setup, users are managed by the operating system. This means every user of the Raspberry Pi can also start their own notebook server.

Admins have additional rights. For example, they can access the Admin Panel from where they can see which users are logged in and start and stop their servers. Admin rights are handled through groups. For example, if we wanted to nominate the user “gerold” as admin, we would first create a group (we could also use a pre-existing one) and add the user to it. This is done as usual in Unix-systems:

sudo addgroup jupyter_admin 
sudo usermod -aG jupyter_admin gerold

Then, we need to add this group as an admin-group in the config-file:

c.PAMAuthenticator.admin_groups = {'jupyter_admin'}

The admin panel can be reached under http://<address of your raspi>:8888/hub/admin .

References

JupyterHub: https://jupyterhub.readthedocs.io/
JupyterLab: https://jupyterlab.readthedocs.io/