Jupyterhub for course ap3122¶

For the course Advanced Optical Imaging (ap3122) a jupyterhub environment has been setup on the server ap3122-jupyter.tnw.tudelft.nl.

This document explains how to setup the server each years and has some troubleshooting advices at the bottom.

Setup for new academic year¶

This section describes how to configure the server for a new academic year. In these instructions we will setup for 2026-2027.

The instructions have to be done on a command line via an ssh-connection to the server and will require sudo-rights (=administrator rights).

login with ssh to ap3122-jupyter.tnw.tudelft.nl via the bastion host linux-bastion-ex.tudelft.nl:

# replace <netid> with your netid
# on your local computer
ssh <netid>@linux-bastion-ex.tudelft.nl
# and then on linux-bastion-ex
ssh <netid>@ap3122-jupyter.tnw.tudelft.nl

turn off jupyterhub:
```
sudo systemctl stop jupyterhub
```

setup the directories for the new academic year:

# create directories
cd /data/jupyterhub
sudo mkdir ap3122-2026-2027
sudo chown grader-ap3122:grader-ap3122 ap3122-2026-2027
sudo mkdir exchange_ap3122-2026-2027
sudo chown grader-ap3122:grader-ap3122 exchange_ap3122-2026-2027

# setup course directory
cd /home/grader-ap3122
sudo -u grader-ap3122 unlink ap3122
sudo -u grader-ap3122 ln -s /data/jupyterhub/ap3122-2026-2027 ap3122

# setup exchange directory
cd /usr/local/share/nbgrader/exchange
sudo unlink ap3122
sudo ln -s /data/jupyterhub/exchange_ap3122-2026-2027 ap3122

# setup home directory
cd /data/jupyterhub
sudo mv home home_ap3122-2025-2026
sudo mkdir home
sudo chmod a+rwx home

archive course, exchange and home directories of previous academic year.

Read and follow these instructions carefully!

The archive is stored on the staff-groups share of TNW-IST-QI. IST being the former name of the department ImPhys and QI being the former name of the cluster CI.

On your local computer in the File Explorer you must create the archive directory 2025-2026/ on staff-groups in the directory /tnw/ist/qi/Archive/ap3122-jupyter/.

Using the ssh connection setup earlier, you now archive the data on ap3122-jupyter to this new directory. As this staff-groups share is not available directly on the ap3122-jupyterhub server a connection is made with the linux-bastion server:
```
cd /data/jupyterhub
# replace <netid> with your netid
sudo rsync -av --no-perms --no-g --progress \
ap3122-2025-2026 exchange_ap3122-2025-2026 home_ap3122-2025-2026 \
<netid>@linux-bastion.tudelft.nl:/tudelft.net/staff-groups/tnw/ist/qi/Archive/ap3122-jupyter/2025-2026/
```
After archiving the data make sure you update the information in the README.md file located on the /tnw/ist/qi/Archive/ap3122-jupyter/ on the staff-groups share.
data removal of previous academic year.

Only remove the data of the previous academic year after careful verifying the data has been archived in the previous step!
```
cd /data/jupyterhub
sudo rm -rf ap3122-2025-2026 exchange_ap3122-2025-2026 home_ap3122-2025-2026
```

configure the users with grading rights in the jupyterhub configuration. Use your editor to edit the file /etc/jupyterhub/jupyterhub_config.py and check and modify the following lines in this file as needed:

c.Authenticator.admin_users = {
   'rligteringen',
   'jeroenkalkman',
   'kgrussmayer',
   'sstallinga',
   'vbrudanin',
   'esberrevoets',
   'wylee',
}

and

c.JupyterHub.load_groups = {
   'formgrade-ap3122': [
      'jeroenkalkman',
      'rligteringen',
      'kgrussmayer',
      'sstallinga',
      'vbrudanin',
      'esberrevoets',
      'wylee',
   ]
}

turn on jupyterhub:
```
sudo systemctl start jupyterhub
```

All is now configured.

Troubleshooting¶

Important: when logging in into the webinterface of jupyterhub https://ap3122-jupyter.tnw.tudelft.nl with your netid as grader, always make sure the right Course is selected! Go to menu “Nbgrader->Course List->ap3122 jupyterhub”. Do not select “ap3122 local”!

First aid when website is not available

Login with ssh and restart jupyterhub:

sudo systemctl restart jupyterhub