Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jupyterhub/jupyterhub-deploy-teaching

Reference deployment of JupyterHub and nbgrader on a single server
https://github.com/jupyterhub/jupyterhub-deploy-teaching

ansible ipython jupyter jupyter-notebook jupyterhub nbgrader teaching

Last synced: 7 days ago
JSON representation

Reference deployment of JupyterHub and nbgrader on a single server

Awesome Lists containing this project

README 

        
# Deploy JupyterHub for teaching



[![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)

[![Documentation Status](http://readthedocs.org/projects/jupyterhub-deploy-teaching/badge/?version=latest)](http://jupyterhub-deploy-teaching.readthedocs.org/en/latest/?badge=latest)



The goal of this repository is to produce a reference deployment of JupyterHub

for teaching with nbgrader.



The repository started from [this deployment](https://github.com/calpolydatascience/jupyterhub-deploy-data301) 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](https://github.com/jupyterhub/jupyterhub-deploy-teaching/issues/48#issuecomment-277407265) 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](http://jupyterhub-deploy-teaching.readthedocs.org/en/latest/installation.html).



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](http://jupyterhub-deploy-teaching.readthedocs.org/en/latest/configure-nbgrader.html). 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](http://jupyterhub-deploy-teaching.readthedocs.org/en/latest/use-nbgrader.html)

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](http://nbgrader.readthedocs.org/en/latest/).



## 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]``