Setup your home JupyterHub on a Raspberry Pi
Start a notebook from any device in your house. One hub for the whole family.
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.
Table of Contents
- 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.
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/