This report describes the multi-user JupyterHub installation in service on the FOSSR HPC cluster: how it is built, why it is built that way, and how one verifies that it works. Every statement was read from the files and from the live state of the two servers, so that every value can be re-checked against the machines. The architecture is dictated by network routing constraints: the JupyterHub server resides inside the compute network (10.141.0.0/16), which is not reachable from the internet and into which the public VM cannot open a connection either. The only path that crosses that boundary reliably is an SSH session started by the login node towards the VM; reversing the direction of that session with -R provides a channel that the public proxy can use as if it were a local service. All other design choices described in this document follow from this single constraint. The design adopts neither Kubernetes nor any other orchestrator: users are not assigned an ephemeral container scheduled by a third-party component, but receive a regular Slurm job, with the same partitions, the same accounting record and the same software environment as an SSH session. The Apptainer container does not contain the Jupyter environment, which is mounted read-only from the shared filesystem: the job inherits the cluster's modules, and the image, of about 160 MB, holds only a compiler and build tools. The document is organised as follows. §1 fixes the actors, addresses and ports (Figure 1); §2 defines the terminology before any file is shown; §3 inventories the processes that are actually running, separating the services that live for weeks from the processes that live as long as one login (Figure 2). §4 provides the walkthrough required by a new system administrator: the twelve steps between a user's click and the start of a kernel, each described together with its characteristic failure, followed by the log of an actual spawn. §5–§7 annotate the actual configuration files in the order the system meets them (the Hub, the unit, PAM/SSSD, the batch script, the container, nginx, the tunnel), and §7.4 documents how the only machine exposed to the internet is protected. §8 describes the user environments, kernels and code-server included; §9 the image releases and the rollback material; §10 the verification procedures; §11 the defects and the recommended actions. Appendix A collects the abbreviations, Appendix B the software versions read from the binaries, Appendix C every file path with its measured size.

JupyterHub on an HPC Slurm cluster with Apptainer containers

Luigi Barbato
Primo
Membro del Collaboration Group
;
Francesco Gargiulo
Ultimo
Membro del Collaboration Group
2026

Abstract

This report describes the multi-user JupyterHub installation in service on the FOSSR HPC cluster: how it is built, why it is built that way, and how one verifies that it works. Every statement was read from the files and from the live state of the two servers, so that every value can be re-checked against the machines. The architecture is dictated by network routing constraints: the JupyterHub server resides inside the compute network (10.141.0.0/16), which is not reachable from the internet and into which the public VM cannot open a connection either. The only path that crosses that boundary reliably is an SSH session started by the login node towards the VM; reversing the direction of that session with -R provides a channel that the public proxy can use as if it were a local service. All other design choices described in this document follow from this single constraint. The design adopts neither Kubernetes nor any other orchestrator: users are not assigned an ephemeral container scheduled by a third-party component, but receive a regular Slurm job, with the same partitions, the same accounting record and the same software environment as an SSH session. The Apptainer container does not contain the Jupyter environment, which is mounted read-only from the shared filesystem: the job inherits the cluster's modules, and the image, of about 160 MB, holds only a compiler and build tools. The document is organised as follows. §1 fixes the actors, addresses and ports (Figure 1); §2 defines the terminology before any file is shown; §3 inventories the processes that are actually running, separating the services that live for weeks from the processes that live as long as one login (Figure 2). §4 provides the walkthrough required by a new system administrator: the twelve steps between a user's click and the start of a kernel, each described together with its characteristic failure, followed by the log of an actual spawn. §5–§7 annotate the actual configuration files in the order the system meets them (the Hub, the unit, PAM/SSSD, the batch script, the container, nginx, the tunnel), and §7.4 documents how the only machine exposed to the internet is protected. §8 describes the user environments, kernels and code-server included; §9 the image releases and the rollback material; §10 the verification procedures; §11 the defects and the recommended actions. Appendix A collects the abbreviations, Appendix B the software versions read from the binaries, Appendix C every file path with its measured size.
2026
Istituto di Calcolo e Reti ad Alte Prestazioni - ICAR - Sede Secondaria Napoli
JupyterHub,batchspawner,Slurm,Apptainer,FreeIPA,SSSD,PAM,nginx,reverse SSH tunnel,permitlisten,Squid,TLS,fail2ban,kernelspec,code-server
File in questo prodotto:
File Dimensione Formato  
Configurazione_JupyterHub_Slurm_Apptainer.pdf

accesso aperto

Tipologia: Documento in Post-print
Licenza: Creative commons
Dimensione 1.86 MB
Formato Adobe PDF
1.86 MB Adobe PDF Visualizza/Apri

I documenti in IRIS sono protetti da copyright e tutti i diritti sono riservati, salvo diversa indicazione.

Utilizza questo identificativo per citare o creare un link a questo documento: https://hdl.handle.net/20.500.14243/608696
Citazioni
  • ???jsp.display-item.citation.pmc??? ND
  • Scopus ND
  • ???jsp.display-item.citation.isi??? ND
social impact