JupyterHub code/doc cleaning & clarifs

roles/jupyterhub/README.md

@@ -7,8 +7,8 @@
   * [Getting Started](https://jupyterhub.readthedocs.io/en/stable/getting-started/)
 * Students create their own accounts on first use — e.g. at http://box.lan/jupyterhub — just as if they're logging in regularly (unfortunately the login screen doesn't make that clear, but the teacher _does not_ need to be involved!)
   * A student can then sign in with their username and password, to gain access to their files (Jupyter Notebooks).
-  * The teacher should set and protect JupyterHub's overall ``Admin`` password, just in case.  As with student accounts, the login screen doesn't make that clear — so just log in with username `Admin` using any password that you want to become permanent.
-* Individual student folders are created in ``/var/lib/private/`` on the Internet-in-a-Box (IIAB) server:
+  * The teacher should set and protect JupyterHub's overall `Admin` password, just in case.  As with student accounts, the login screen doesn't make that clear — so just log in with username `Admin` using any password that you want to become permanent.
+* Individual student folders are created in `/var/lib/private/` on the Internet-in-a-Box (IIAB) server:
   * A student will only be able to see their own work — they do not have privileges outside of their own folder.
   * Students may upload Jupyter Notebooks to the IIAB server, and download the current state of their work via a normal browser.
 
@@ -34,7 +34,7 @@ Passwords are hashed using 4096 rounds of the latest Blowfish (bcrypt's $2b$ alg
 
 Users can change their password by first logging into their account and then visiting URL: http://box.lan/jupyterhub/auth/change-password
 
-This is the only way to change the Admin user's password, because the Control Panel > Admin (below) does not permit deletion of the Admin account.  It will be necessary to restart JupyterHub before the changed password becomes effective:
+NOTE: This is the only way to change the password for user 'Admin', because Control Panel > Admin (below) does not permit deletion of this account.
 
 ```
 sudo systemctl restart jupyterhub
@@ -42,9 +42,9 @@ sudo systemctl restart jupyterhub
 
 ### Control Panel > Admin page, to change user passwords
 
-Admin users can reset user passwords by deleting the user from the JupyterHub Admin page.  This logs the user out, but does not remove any of their data or home directories.  The user can then set a new password by logging in again with a new password.
+The 'Admin' user (and any users given 'Admin' privilege) can reset user passwords by deleting the user from JupyterHub's **Admin** page (below).  This logs the user out, but does not remove any of their data or home directories.  The user can then set a new password in the usual way — simply by logging in:
 
-1. As an Admin user, click **Control Panel** in the top right of your JupyterHub.
+1. As a user with 'Admin' privilege, click **Control Panel** in the top right of your JupyterHub.
 
    ![Control panel button in notebook, top right](control-panel-button1.png)
 
@@ -60,10 +60,12 @@ Admin users can reset user passwords by deleting the user from the JupyterHub Ad
 
    If there is a confirmation dialog, confirm the deletion.  This will also log the user out if they were currently running.
 
-4. Re-create the user whose password needs resetting within that same dialog.
+4. Re-create the user whose password needs resetting, on this same screen.
 
 5. Ask the user to log in, but with a new password of their choosing.  This will be their password going forward.
 
+_WARNING: If on login users see "500 : Internal Server Error", you may need to remove ALL files of the form_ `/run/jupyter-johndoe-singleuser`
+
 ### PAWS/Jupyter Notebooks for Python Beginners
 
 While PAWS is a little bit off topic, if you have an interest in Wikipedia, please do see this 23m 42s video ["Intro to PAWS/Jupyter notebooks for Python beginners"](https://www.youtube.com/watch?v=AUZkioRI-aA&list=PLeoTcBlDanyNQXBqI1rVXUqUTSSiuSIXN&index=8) by Chico Venancio, from 2021-06-01.

roles/jupyterhub/tasks/install.yml

@@ -59,22 +59,22 @@
     src: jupyterhub.service.j2
     dest: /etc/systemd/system/jupyterhub.service
 
-- name: Install script from template, to fix the async bug in firseuseauthenticator
+- name: Install {{ jupyterhub_venv }}/bin/getsite.py from template, to fetch site_packages path, e.g. {{ jupyterhub_venv }}/lib/python{{ python_ver }}/site-packages
   template:
-    src: patch_await.sh.j2
-    dest: "{{ jupyterhub_venv }}/bin/patch_await.sh"
+    src: getsite.py.j2
+    dest: "{{ jupyterhub_venv }}/bin/getsite.py"
     mode: 0755
 
-- name: Install {{ jupyterhub_venv }}/bin/getsite.py from template, to fetch the site_packages path
+- name: Install patch_FUA.sh from template -- to (1) fix async password-changing page, and (2) force usernames to lowercase -- patching $SITE_PACKAGES/firstuseauthenticator/firstuseauthenticator.py
   template:
-      src: getsite.py.j2
-      dest: "{{ jupyterhub_venv }}/bin/getsite.py"
-      mode: 0755
+    src: patch_FUA.sh.j2
+    dest: "{{ jupyterhub_venv }}/bin/patch_FUA.sh"
+    mode: 0755
 
-- name: "Run the above two, via: {{ jupyterhub_venv }}/bin/patch_await.sh"
-  command: "{{ jupyterhub_venv }}/bin/patch_await.sh"
+- name: "Run the above two, via: {{ jupyterhub_venv }}/bin/patch_FUA.sh"
+  command: "{{ jupyterhub_venv }}/bin/patch_FUA.sh"
 
-- name: Install script from template, to turn off the warning about http insecurity
+- name: Install patch_http-warning.sh from template, to turn off the warning about http insecurity, in {{ jupyterhub_venv }}/share/jupyterhub/templates/login.html
   template:
     src: patch-http-warning.sh.j2
     dest: "{{ jupyterhub_venv }}/bin/patch_http-warning.sh"

roles/jupyterhub/templates/jupyterhub_config.py.j2

@@ -1057,7 +1057,7 @@ c.JupyterHub.spawner_class = 'systemdspawner.SystemdSpawner'
 #  
 #  Defaults to an empty set, in which case no user has admin access.
 #  Default: set()
-c.Authenticator.admin_users = set(['Admin'])
+c.Authenticator.admin_users = set(['admin'])
 c.Authenticator.dbm_path = "{{ jupyterhub_venv }}/etc/passwords.dbm"
 
 ## Set of usernames that are allowed to log in.

roles/jupyterhub/templates/patch_FUA.sh.j2

@@ -0,0 +1,16 @@
+#!/bin/bash -x
+# Apply 2 patches to firstuseauthenticator.py
+
+# SITE_PACKAGES=$({{ jupyterhub_venv }}/bin/python -m site | grep {{ jupyterhub_venv }} | grep /site-packages | cut -d\' -f2)
+SITE_PACKAGES=$({{ jupyterhub_venv }}/bin/getsite.py)
+file=$SITE_PACKAGES/firstuseauthenticator/firstuseauthenticator.py
+# e.g. /opt/iiab/jupyterhub/lib/python3.9/site-packages/firstuseauthenticator/firstuseauthenticator.py
+
+# (1) Add await to asyncio change password function:
+# https://github.com/iiab/iiab/issues/2918 == JupyterHub password-changing page shows "500 : Internal Server Error"
+# https://github.com/jupyterhub/firstuseauthenticator/issues/36 == 500 Error on path /hub/auth/change-password
+# https://github.com/jupyterhub/firstuseauthenticator/pull/37 == proposed fix to issue 36
+sed -i 's/= self\.render/= await self.render/' $file
+
+# (2) https://github.com/jupyterhub/firstuseauthenticator/pull/38 == lowercase username to lock password
+sed -i "s/data\['username'\]$/&.lower()/" $file

roles/jupyterhub/templates/patch_await.sh.j2

@@ -1,17 +0,0 @@
-#!/bin/bash -x
-# add await to asyncio change password function
-
-# SITE_PACKAGES=$({{ jupyterhub_venv }}/bin/python -m site | grep {{ jupyterhub_venv }} | grep /site-packages | cut -d\' -f2)
-
-SITE_PACKAGES=$({{ jupyterhub_venv }}/bin/getsite.py)
-file=$SITE_PACKAGES/firstuseauthenticator/firstuseauthenticator.py
-
-# file={{ jupyterhub_venv }}/lib/python{{ python_ver }}/site-packages/firstuseauthenticator/firstuseauthenticator.py
-# e.g. /opt/iiab/jupyterhub/lib/python3.9/site-packages/firstuseauthenticator/firstuseauthenticator.py
-
-if grep -q 'await self.render' $file; then
-    echo Patch already applied. Skipping. . .
-else
-    echo Updating $file
-    sed -i 's/self.render/await self.render/' $file
-fi