isabella232 / jupyterhub-deploy-teaching

Reference deployment of JupyterHub and nbgrader on a single server

Deploy JupyterHub for teaching

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

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

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

Design goal of this reference deployment

Create a JupyterHub teaching reference deployment that is simple yet functional:

• Use a single server.
• Use Nginx as a frontend proxy, serving static assets, and a termination point 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 GitHub users 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 a user-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 your cloud 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 the steps in the Installation Guide.

View the documentation for detailed configuration steps. The basic steps to configure 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 section of the reference deployment documentation gives brief instructions about creating course assignments, releasing them to students, and grading student submissions.

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 the Ansible deploy commands:

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

Authentication

If you are not using GitHub OAuth, you will need to manually create users using 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 server and run: supervisorctl jupyterhub [start|stop|restart]