Moving from BinderHub to Zero-to-JupyterHub

[sgibson91]

Summary

A BinderHub isn't the most useful platform for a research community - it generally lacks persistence (although you can rectify this by deploying the persistent_binderhub helm chart) and configuring safe git push/pull to any kind of repository is clunky.

A lot of work has been going on in the z2jh-k8s helm chart by 2i2c and other parties to make this a useful platform for research purposes.

Must-Have Features

• Azure AD authentication, so everyone can log in with their turing.ac.uk account
  • Docs: https://zero-to-jupyterhub.readthedocs.io/en/latest/administrator/authentication.html#azure-active-directory
  • Turing IT will need to create a relevant app and provide the client ID and secret for that app
  • Not applicable. See https://github.com/alan-turing-institute/hub23-deploy/issues/426#issuecomment-1109542663
• Mapping specific user groups onto specific profile lists (i.e. machine types)
  • https://discourse.jupyter.org/t/tailoring-spawn-options-and-server-configuration-to-certain-users/8449
• Secure GitHub pull/push access to public/private repos both in the Turing GitHub org and users' own personal accounts
  • https://github.com/yuvipanda/github-app-user-auth
  • We will need to provide user-facing docs clearly demonstrating how to generate a token from the command line and from a notebook, and clearly state that this token only lasts 8 hours.
  • https://github.com/alan-turing-institute/hub23-deploy/issues/272
• Ability to sync folders to the Jupyter home dir server
  • https://github.com/yuvipanda/jupyter-syncthing-proxy
  • Also provide user-facing docs on how to use this feature
• A hub environment image where all the packages users will need to use are installed
  • 2i2c has a template repository for automatically building and pushing a docker image using the repo2docker-action: https://github.com/2i2c-org/hub-user-image-template
  • Note: this example suggests pushing to quay.io, but a lot of other container registries are supported too, so we could push to the turinginst org on Docker Hub, for example
  • We probably want to start with an image like Pangeo's and then start crowd-sourcing a list of packages people actually want and provide them in our own image

Nice-to-Have Features

• SSH access
  • https://github.com/yuvipanda/jupyterhub-ssh

Future Features

These features are still under active development and are not yet recommended for production deployment. But when they are, they'll be super awesome!

• Real-Time Collaboration in JupyterLab
  • https://jupyterlab.readthedocs.io/en/stable/user/rtc.html
• Accessing private data based in the cloud
  • https://github.com/alan-turing-institute/hub23-deploy/issues/273
• Dynamic environment generation using repo2docker directly from JupyterHub
  • 2i2c will be working on this feature sometime next year

TODOs

1. Tear down Hub23 the BinderHub
2. Deploy Hub23 the JupyterHub

Tearing down the BinderHub

• Documentation to achieve this is available here and here
• Hub23 and the Binder Federation deployment share the same cluster, so we may not want to totally delete the cluster... Or maybe we do and want to redeploy into the uksouth location while we have the opportunity. Up to you!

Clearing out the repo

Files we won't need (or will be creating new ones for JupyterHub):

• Everything under the deploy/ folder
• Everything under the hub23-chart/ folder (we should create a new local helm chart that has ingress-nginx, grafana and prometheus dependencies for monitoring)
  • https://github.com/alan-turing-institute/hub23-deploy/issues/41
• .az-pipelines/cd.yaml will need rewriting and temporarily disabling until we have the new deployment set up
  • https://github.com/alan-turing-institute/hub23-deploy/issues/379 is a critical issue for this step
• Disable .github/workflows/bump-helm-version.yaml
  • If we end up with a new local helm chart, we can reenable this
• We should probably rewrite the admin docs under the docs/ folder as we go too

Setting up the new JupyterHub

• Deploy the z2jh helm chart in a useful manner
  • Take inspiration from 2i2c's basehub for this: https://github.com/2i2c-org/infrastructure/tree/master/helm-charts/basehub
  • We should set up a new local helm chart that depends on
  • z2jh
  • ingress-nginx: load balancer
  • prometheus: for metrics collection
  • grafana: graphing the metrics collected by prometheus
  • A useful set of grafana dashboards for JupyterHubs are available here: https://github.com/jupyterhub/grafana-dashboards
• Reenable CI/CD
  • Make any tweaks to .az-pipelines/cd.yaml to get it running again, or...
  • Migrate to GitHub Actions. 2i2c has code for securely accessing Azure resources from GitHub Actions.
  • Reenable .github/workflows/bump-helm-version.yaml for new local helm chart
• Make user-facing docs accessible via a hub service, a la 2i2c: https://github.com/2i2c-org/infrastructure/blob/d9c49323892e18ebb539a7611cb33684641b1acf/config/clusters/2i2c/staging.values.yaml#L1-L6

Next Steps

• Start enabling the features listed at the top of this issue!
  • Some of them will require editing config at the helm chart level, other things are just making sure the packages are installed in the hub environment and providing docs
• Start promoting the hub in the Turing community, what it can do, and why it's useful
• Teach people how to use nbgitpuller to sync git repositories to the JupyterHub
  • https://jupyterhub.github.io/nbgitpuller/

[sgibson91]

• Azure AD authentication, so everyone can log in with their turing.ac.uk account
  • Docs: zero-to-jupyterhub.readthedocs.io/en/latest/administrator/authentication.html#azure-active-directory
  • Turing IT will need to create a relevant app and provide the client ID and secret for that app
• Mapping specific user groups onto specific profile lists (i.e. machine types)
  • discourse.jupyter.org/t/tailoring-spawn-options-and-server-configuration-to-certain-users/8449

Note that for the second point, we must use GitHub-based authentication - so the first point is not applicable

[sgibson91]

Here is a nice implementation of allowing specific GitHub Teams access to specific machine types via profileList (note this will eventually be upstreamed to the z2jh helm chart)

• https://github.com/2i2c-org/infrastructure/pull/1239