JupyterHub Preparation

This bonus section describes an Ansible playbook that can be used to automate the deployment of a JupyterHub server that supports containerization via Podman. This playbook builds the same infrastructure as the one used in the tutorial.

Ansible installation

Although Ansible can also be used on Windows via Python, it is better to run it in a Linux environment (if you use Windows, we recommend using WSL). The following installation steps are thus focused only on Linux, specifically Debian-based systems (see the official documentation for other installation options).

# Add the Ansible repository:
linux:$ sudo add-apt-repository --yes --update ppa:ansible/ansible
linux:$ sudo apt update
# Install Ansible:
linux:$ sudo apt install ansible -y
# Validate Ansible installation:
linux:$ ansible --version

Ansible playbook

The Ansible playbook for installing JupyterHub with Podman support is publicly available at https://gitlab.ics.muni.cz/csirt-mu-analytics-public/ansible-jupyterhub. Before running, setting the playbook variables in ./group_vars/all/main.yml file is necessary. Specifically, please provide the name of the JupyterHub administrator account and its password. You may create a copy of the main.yml.example file or use the following template (please do not forget to add --- at the file beginning):

---

administrator_account:
  name: administrator
  password: <PASSWORD>

To start the Ansible playbook, change your directory to the repository root and run the following commands. To run correctly, you need to replace the <XXX> values:

• <SERVER_IP> – IP address or hostname of the server where the JupyterHub should be installed,
• <USERNAME> – name of the server user with administrator privileges,
• <SSH_PRIVATE_KEY> – your SSH private key for login to the defined user name.

linux:$ ssh-agent bash
linux:$ ssh-add <SSH_PRIVATE_KEY>
linux:$ ansible-playbook -i "<SERVER_IP>," --private-key <SSH_PRIVATE_KEY> -u <USERNAME> playbook.yml
# Close SSH agent when no longer needed:
linux:$ ssh-agent -k

Running the Ansible playbook will sequentially execute the three defined roles described below.

Role jupyterhub

This role installs the Littlest Jupyter Hub (see https://tljh.jupyter.org/) and creates an administrator account with credentials provided in the playbook configuration. After successful installation, the following modules are set up:

• nbgitpuller – Jupyter server extension to sync a git repository one-way to a local path.
• jupyterlab-unfold – An IDE-like file browser for JupyterLab.
• voila – Module allowing the conversion of a Jupyter Notebook into an interactive dashboard.

In the final part of the playbook role, the TLJH and Voila configurations are made. Details of the settings used can be found in the file roles/jupyterhub/tasks/configure.yml.

Role nginx

This role installs the nginx web server that provides a proxy for JupyterHub. The role also creates a self-signed TLS certificate to allow HTTPS connection to the JupyterHub. Connecting to HTTPS will display a TLS validation error, but everything will work if you enable the exception. For a valid TLS connection, you must obtain certificates using a valid certificate authority (e.g., Let's Encrypt).

Role podman

This role installs the Podman container manager which allows you to run the provided toolbox container images.

As JupyterHub is using some containerization to spawn JupyterLab for individual users, it is impossible to use the $ podman command (users must have access to the $ sudo command for this to work). The Ansible playbook role provided overcomes this problem by creating a custom Spawner that allows ordinary users to run $ sudo (they can access $ sudo, but they are still not in the sudoers file and thus are not able to get administrative privileges). The spawner code is available in the roles/podman/files/custom_spawner.py file. To make the role even more secure, it prevents normal users (account starting with jupyter-) from running $ su command, which would otherwise be possible thanks to the spawner change.