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
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 126.96.36.199 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
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.
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
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
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.
Ansible configuration and deployment
Change the ansible configuration by editing
To limit the deployment to certain hosts, add
-l hostname to the
Ansible deploy commands:
ansible-playbook -i hosts -l hostname deploy.yml
If you are not using GitHub OAuth, you will need to manually create users
adduser --gecos "" username.
The logs for jupyterhub are in
The logs for nbgrader are in
Starting, stopping, and restarting the Hub
To manage the jupyterhub and nbgrader services by SSH to the server
supervisorctl jupyterhub [start|stop|restart]