Intalling in a Regular JupyterHub Environment as a Managed Service

This guide assumes you already know how to set up a JupyterHub environment. You should also be familiar with adding JupyterHub-managed services into jupyterhub_config.py.

If you prefer looking at examples instead, here’s a sample installation setup. It doesn’t demonstrate all the configurable options, though.

Installing ngshare

First, you should install ngshare in the same environment as the hub.

python3 -m pip install ngshare

After it’s installed, you should tell JupyterHub to spawn ngshare as a managed service on startup. This can be done using something like this inside jupyterhub_config.py:

c.JupyterHub.services.append(
    {
        'name': 'ngshare',
        'url': 'http://127.0.0.1:10101',
        'command': ['python3', '-m', 'ngshare', '--admins', 'admin,admin2'],
    }
)

You may want to check the list of command line arguments for further configuration. JupyterHub will automatically spawn ngshare on port 10101 in this case.

After you restart JupyterHub, 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.

Environment variables

Like other Services and JupyterHub itself ngsahre support some configuration via the environment.

The follwing configuration might be necessary in case the JupyterHub is running behindd a reverse proxy. JUPYTERHUB_SERVICE_REDIRECT_URL is the URL that ngshare calles after the oauth authentication with the hub. For example: /my_hub_proxy_prefix/services/ngshare/`. The default values is /services/ngshare/`.

Example for hub-managed-services: .. code:: python

c.JupyterHub.services.append(

{

‘name’: ‘ngshare’, ‘url’: ‘http://127.0.0.1:10101’, ‘command’: [‘python3’, ‘-m’, ‘ngshare’, ‘–admins’, ‘admin,admin2’], ‘environment’: { ‘JUPYTERHUB_SERVICE_REDIRECT_URL’: ‘/my_hub_proxy_prefix/services/ngshare/’}

}

)

Installing ngshare_exchange

ngshare_exchange can be installed like any other python package:

python3 -m pip install ngshare_exchange

Finally, you need to configure nbgrader to use ngshare_exchange. This can be done by adding the following to nbgrader’s global config file, /etc/jupyter/nbgrader_config.py:

from ngshare_exchange import configureExchange
c=get_config()
# Note: It's important to specify the right ngshare URL when not using k8s
configureExchange(c, 'http://127.0.0.1:10101/services/ngshare')

# Add the following to let students access courses without configuration
# For more information, read Notes for Instructors in the documentation
c.CourseDirectory.course_id = '*'

You will have to specify the right URL to ngshare inside configureExchange. This is usually http://ip:port/services/ngshare where ip is the hub’s IP and port is the port ngshare runs on. Make sure each user can access this endpoint.

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.