Deploy JupyterHub for teaching

The goal of this repository is to produce a reference deployment of JupyterHubfor teaching with nbgrader.

The repository started from this deployment of JupyterHubfor "Introduction to Data Science" at Cal Poly.It is designed to be a simple and reusable JupyterHub deployment, whilefollowing best practices.

The main use case targeted is small to medium groups of trusted usersworking on a single server.

Design goal of this reference deployment

Create a JupyterHub teaching reference deployment that is simple yetfunctional:

• Use a single server.
• Use Nginx as a frontend proxy, serving static assets, and a terminationpoint for SSL/TLS.
• Configure using Ansible scripts.
• Use (optionally) https://letsencrypt.org/ for generating SSL certificates.
• Does not use Docker or containers

Prerequisites

To deploy this JupyterHub reference deployment, you should have:

• An empty Ubuntu server running the latest stable release
• Local drives to be mounted
• A formatted and mounted directory to store user home directories
• A valid DNS name
• SSL certificate
• Ansible 2.1+ installed for JupyterHub configuration (pip install "ansible>=2.1")
  • Verified Ansible 2.2.1.0 works with Ubuntu 16.04 and Python3

For administration of the server, you should also:

• Specify the admin users of JupyterHub.
• Allow SSH key based access to server and add the public SSH keys of GitHubusers who need to be able to SSH to the server as root for administration.

For managing users and services on the server, you will:

• Create "Trusted" users on the system, meaning that you would give them auser-level shell account on the server
• Authenticate and manage users with either:
  • Regular Unix users and PAM.
  • GitHub OAuth
• Manage the running of jupyterhub and nbgrader using supervisor.
• Monitor the state of the server (optional feature) using NewRelic or yourcloud provider.

Installation

Follow the detailed instructions in the Installation Guide.

The basic steps are:

• Create the hosts group with Fully Qualified Domain Names (FQDNs) of the hosts
• Secure your deployment with SSL
• Deploy with Ansible ansible-playbook -i hosts deploy.yml
• Verify your deployment and reboot the Hub supervisorctl reload

Configuring nbgrader

The nbgrader package is installed when JupyterHub is installed using thesteps in the Installation Guide.

View the documentation for detailed configuration steps. The basic steps toconfigure formgrade or nbgrader's notebook extensions are:

• activate the extension nbgrader extension activate
• log into JupyterHub
• run ansible script ansible-playbook -i hosts deploy_formgrade.yml
• SSH into JupyterHub
• reboot the Hub and nbgrader supervisorctl reload

Using nbgrader

With this reference deployment, instructors can start to use nbgrader.The Using nbgrader sectionof the reference deployment documentation gives brief instructions aboutcreating course assignments, releasing them to students, and grading studentsubmissions.

For full details about nbgrader and its features, see the nbgrader documentation.

Notes

Ansible configuration and deployment

Change the ansible configuration by editing ./ansible_cfg.

To limit the deployment to certain hosts, add -l hostname to theAnsible deploy commands:

ansible-playbook -i hosts -l hostname deploy.yml

Authentication

If you are not using GitHub OAuth, you will need to manually create usersusing adduser: adduser --gecos "" username.

Logs

The logs for jupyterhub are in /var/log/jupyterhub.

The logs for nbgrader are in /var/log/nbgrader.

Starting, stopping, and restarting the Hub

To manage the jupyterhub and nbgrader services by SSH to the serverand run: supervisorctl jupyterhub [start|stop|restart]