Installing on a Z2JH Cluster¶
This guide assumes you already have a Kubernetes cluster with a persistent volume provisioner (which should be the case if you run Z2JH). You should also be familiar with installing Z2JH and using Helm.
If you prefer looking at examples instead, here’s a sample installation setup. It doesn’t demonstrate all the configurable options, though.
Installing ngshare¶
Installing the Helm Chart¶
ngshare
is prepackaged into a Helm chart. You may add the repo like this:
helm repo add ngshare https://libretexts.github.io/ngshare-helm-repo/
helm repo update
Afterwards, create a config.yaml
file to customize your helm chart. Here’s a bare minimum config.yaml
file that assumes you’re installing ngshare
into the same namespace as Z2JH, and that you only need 1GB of storage in total:
ngshare:
hub_api_token: demo_token_9wRp0h4BLzAnC88jjBfpH0fa4QV9tZNI
admins:
- admin_username
The API token should be generated randomly and kept secret (if you omit it, one will be automatically generated for you).
Here’s a sample config.yaml
file that contains the most commonly used options:
deployment:
# Resource limitations for the pod
resources:
limits:
cpu: 100m
memory: 128Mi
requests:
cpu: 100m
memory: 128Mi
ngshare:
hub_api_token: demo_token_9wRp0h4BLzAnC88jjBfpH0fa4QV9tZNI
# Please change the line below with the namespace your Z2JH helm chart is installed under
# You can omit this value if you're installing ngshare in the same namespace
hub_api_url: http://hub.your-z2jh-namespace.svc.cluster.local:8081/hub/api
admins:
- admin1
- admin2
pvc:
# Amount of storage to allocate
storage: 1Gi
For a full list of configurable values, check here.
You can now install ngshare
using Helm:
# For helm3
helm install ngshare ngshare/ngshare -f config.yaml
# For helm2
helm install ngshare/ngshare -n ngshare -f config.yaml
If you didn’t install Z2JH in the default namespace, it is recommended to install ngshare
in the same namespace as Z2JH by specifying --namespace your_namespace_name
in helm install
. Note that if you don’t put ngshare
and Z2JH in the same namespace, you will have to modify the ngshare.hub_api_url
value in your config to point to http://hub.your-z2jh-namespace.svc.cluster.local:8081/hub/api
instead (replace your-z2jh-namespace
with the namespace where Z2JH is installed).
After installation, Helm should give you some instructions on how to configure Z2JH.
Configuring Z2JH to Work with ngshare¶
The ngshare
Helm chart should output something like this at the end of installation:
Congrats, ngshare should be installed!
To get started, add the following to your JupyterHub helm chart's values:
hub:
extraConfig:
ngshare.py: |
c.JupyterHub.services.append({
'name': 'ngshare',
'url': 'http://ngshare.default.svc.cluster.local:8080',
'api_token': '3VEgEzkhFkQsdZNI7zhnyMW6U0a2xsZq'})
Follow the instructions and add the code block to your Z2JH config.yaml
. After you have updated Z2JH’s configuration using helm upgrade
, you can verify the service is working as intended by logging into JupyterHub, clicking “Control Panel”, then “Services -> ngshare”. If you see the ngshare
welcome page, you may proceed.
Installing ngshare_exchange¶
You should know how to customize the user environment using Dockerfiles in Z2JH. For the clients to use ngshare
, the exchange must be installed in every user pod.
ngshare_exchange
only works with nbgrader version 0.7.0 or above. Unfortunately, that version is not yet released. You will have to install the latest nbgrader from GitHub first:
python3 -m pip install git+https://github.com/jupyter/nbgrader.git@5a81fd5
jupyter nbextension install --symlink --sys-prefix --py nbgrader
jupyter nbextension enable --sys-prefix --py nbgrader
jupyter serverextension enable --sys-prefix --py nbgrader
Afterwards, you may install ngshare_exchange
:
python3 -m pip install ngshare_exchange
Finally, you need to configure nbgrader to use ngshare_exchange. This can be done by adding some code to nbgrader’s global config file, /etc/jupyter/nbgrader_config.py
. The relevant code should be output by the helm install
command earlier when you installed ngshare
:
from ngshare_exchange import configureExchange
c=get_config()
configureExchange(c, 'http://ngshare.default.svc.cluster.local:8080/services/ngshare')
# Add the following line to let students access courses without configuration
# For more information, read Notes for Instructors in the documentation
c.CourseDirectory.course_id = '*'
Depending on your helm values and the namespace you install in, the URL will be different. Be sure to follow the code your helm install
command outputs.
A sample singleuser Dockerfile that does all of the above is available on Github.
If running nbgrader list
doesn’t cause any significant errors, you have installed ngshare_exchange
correctly. Please check Notes for Administrators and Notes for Instructors for more information on how to use ngshare
. The students should be able to use nbgrader as normal without additional configuration.