Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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: 6 days ago
JSON representation
Reference deployment of JupyterHub and nbgrader on a single server
- Host: GitHub
- URL: https://github.com/jupyterhub/jupyterhub-deploy-teaching
- Owner: jupyterhub
- License: bsd-3-clause
- Created: 2016-04-14T13:56:15.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-06-11T23:17:18.000Z (7 months ago)
- Last Synced: 2024-12-29T14:19:07.719Z (13 days ago)
- Topics: ansible, ipython, jupyter, jupyter-notebook, jupyterhub, nbgrader, teaching
- Language: Jinja
- Homepage: http://jupyterhub-deploy-teaching.readthedocs.io/en/latest/
- Size: 196 KB
- Stars: 247
- Watchers: 17
- Forks: 86
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: security/.gitignore
Awesome Lists containing this project
- awesome-starred - jupyterhub/jupyterhub-deploy-teaching - Reference deployment of JupyterHub and nbgrader on a single server (ansible)
- awesome-list-ansible - jupyterhub-deploy-teaching
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 Python3For *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]``