Simplify setup with make and new inventory file

Makefile

@@ -0,0 +1,48 @@
+.PHONY: all prepare venv lint test clean
+
+SHELL=/bin/bash
+
+VENV_NAME?=venv
+VENV_BIN=$(shell pwd)/${VENV_NAME}/bin
+VENV_ACTIVATE=. ${VENV_BIN}/activate
+
+PYTHON=${VENV_BIN}/python3
+
+TEST?=bar
+
+all:
+	@echo "make prepare"
+	@echo "    Create python virtual environment and install dependencies."
+	@echo "make lint"
+	@echo "    Run list on project."
+	@echo "make test"
+	@echo "    Run tests on project."
+	@echo "make deploy"
+	@echo "    Run deployment scripts."
+	@echo "make clean"
+	@echo "    Remove python artifacts and virtualenv."
+
+prepare:
+	which virtualenv || python3 -m pip install virtualenv
+	make venv
+
+venv:
+	test -d $(VENV_NAME) || virtualenv -p python3 $(VENV_NAME)
+
+	${PYTHON} -m pip install -r requirements.txt
+	${PYTHON} -m pip install -r dev-requirements.txt
+
+deploy:
+	ansible-playbook -i ansible/hosts \
+      ansible/provisioning.yml
+
+lint: venv
+	${VENV_BIN}/flake8 src
+	${VENV_BIN}/ansible-lint
+
+test: venv
+	${PYTHON} -m pytest -vv tests
+
+clean:
+	find . -name '*.pyc' -exec rm -f {} +
+	rm -rf $(VENV_NAME) *.eggs *.egg-info dist build docs/_build .cache

README.md

@@ -7,90 +7,69 @@
 
 ## Overview
 
-JupyterHub + docker + nbgrader
+[Jupyter Notebooks](https://jupyter.org) are a great **education tool** for a variety of subjects since it offers instructors and learners a unified document standard to combine markdown, code, and rich visualizations. With the proper setup, Jupyter Notebooks allow organizations to enhance their learning experiences.
 
-## Prerequisites
+When combined with the [nbgrader](https://github.com/jupyter/nbgrader) package instructors are able to automate much of tasks associated with grading and providing feedback for their users.
 
-On remote host:
+## Why?
 
-- Tested with Ubuntu 18.04
+Running a multi-user setup using [JupyterHub](https://github.com/jupyterhub/jupyterhub) and `nbgrader` with `docker containers` requires some additional setup. Some of the questions this distribution attempts to answer are:
 
-On machine running `ansible-playbook`:
+- How do we manage authentication when the user isn't a system user within the JupyterHub or Jupyter Notebook container?
+- How do we manage permissions for student and instructor folders?
+- How do we securely syncronize information with the Learning Management System (LMS) using the [LTI 1.1 and LTI 1.3](https://www.imsglobal.org/activity/learning-tools-interoperability) standards?
+- How do we improve the developer experience to provide more consistency with versions used in production, such as with Kubernetes?
+- How should deployment tools reflect these container-based requirements and also (to the extent possible) offer users an option that is cloud-vendor agnostic?
 
-- [Virtualenv](https://pypi.org/project/virtualenv/1.7.1.2/)
+Our goal is to remove these obstacles so that you can get on with the teaching!
 
 ## Quick Start
 
-### Set up virtual environment and install requirements
-
-1. Clone this repo:
-
-    git clone https://github.com/IllumiDesk/illumidesk
-
-2. Activate a virtual environment with Python 3.6+:
+Follow these instructions to install the system with a set of sensible defaults. Refer to the [customization](#customization) section for more advanced setup options.
 
-    virtualenv -p python3 venv
-    source venv/bin/activate
+### Prerequisites
 
-3. Install requirements:
+On remote host:
 
-    python3 -m pip install -r requirements.txt
+- Tested with Ubuntu 18.04
 
-> `Note`: depending on your server's resource the ansible script can take anywhere between 5/10 minutes. Most of this time is spent building the images themselves as they are not stored in a docker registry.
+### Prepare your setup
 
-### Prepare configuration to run ansible playbook
+1. Clone and change directories into this repo's root:
 
-1. Change into the ansible directory:
+    git clone https://github.com/IllumiDesk/illumidesk
+    cd illumidesk
 
-    cd ansible
+2. Create a new hosts file from the provided YML template.
 
-2. Create a `ansible/hosts` file from the provided `ansible/hosts.example`:
+    cp ansible/hosts.example ansible/hosts
 
-    cp `ansible/hosts.example` `ansible/hosts`
+3. Update the `ansible/hosts` file:
+
+    - ansible_host: target server IPv4 address
+    - ansible_port: target server port (default 22)
+    - ansible_user: target server username
+    - ansible_ssh_private_key_file: full path to SSH private key file used for SSH
+    - ansible_password: optional value used when the target server requires a username/password
 
-3. Update `ansible_ssh_host` with your instance's IPv4 address.
+4. Run the deployment script (the script will prompt you for certain values):
 
-4. Run `ansible-playbook` using the flags below:
+    make deploy
 
-- (Not required for all instances) Remote server SSH private key: `--private-key`
-- Remote user: `-u`
-- Extra variables: `--extra-vars`
-  - Organization name: `org_name`
-  - Top level domain name: `tld`
+5. Once the ansible playbook has finished running the JupyterHub should be available at:
 
-The combination of the `org_name` and the `tld` create the remot host's domain name. For example, if `org_name` is `my-edu` and `tld` is `example.com`, then the remote host's domain name is `my-edu.example.com`.
+    `http://<target_ipv4>:8000/`
 
-> **NOTE**: some instances disable the `root` user by default. If you use a user other than `root`, ensure that you use a user that is a member of the `sudoers` group.
-
-For example:
-
-```bash
-ansible-playbook \
-  provisioning.yml \
-  --private-key /path/to/server/private/key \
-  -u ubuntu \
-  --extra-vars \
-  "org_name=my-edu \
-  tld=example.com" \
-  -v
-```
-
-You may add any of the variables listed in `ansible/group_vars/all.yml` when running the playbook.
-
-6. Once the ansible playbook has finished running the JupyterHub should be available at:
-
-    `http://<public_ipv4>:8000/`
-
-7. Login with either the instructor or student accounts:
+6. Login with either the instructor or student accounts:
 
 - **Instructor Role**: instructor1
 - **Student Role**: student1
 
-> **Tip**: To confirm the values you will need for `ansible-playbook`, log into your remote instance with SSH. This will allow you to confirm:
+> **Tip**: To confirm the values you will need for `ansible-playbook`, log into your remote instance with SSH. This will allow you to confirm settings such as:
 
-> - Which user you connect with
-> - Whether or not you need a PEM key file
-> - Your remote IP address
+> - The username for the target server
+> - The private key required for the target server's SSH key
+> - Etc
 
 ### Initial Course Setup
 
@@ -122,9 +101,38 @@ By default, this setup uses the `FirstUseAuthenticator` and as such accepts any
 
 ## Customization
 
-### LTI Authenticator
+You may customize your setup by using the `--extra-args` flag and passing additional variables and their values to override the provided defaults.
+
+For example, you can run the `ansible-playbook` using the flags below:
+
+- (Not required for all instances) Remote server SSH private key: `--private-key`
+- Remote user: `-u`
+- Extra variables: `--extra-vars`
+  - Organization name: `org_name`
+  - Top level domain name: `tld`
+
+The combination of the `org_name` and the `tld` create the remot host's domain name. For example, if `org_name` is `my-edu` and `tld` is `example.com`, then the remote host's domain name is `my-edu.example.com`.
+
+> **NOTE**: some instances disable the `root` user by default. If you use a user other than `root`, ensure that you use a user that is a member of the `sudoers` group.
+
+For example:
+
+```bash
+ansible-playbook \
+  provisioning.yml \
+  --private-key /path/to/server/private/key \
+  -u ubuntu \
+  --extra-vars \
+  "org_name=my-edu \
+  tld=example.com" \
+  -v
+```
+
+You may add any of the variables listed in `ansible/group_vars/all.yml` when running the playbook.
+
+### LTI 1.1 Authenticator
 
-Open the JupyterHub configuration file located in `ansible/roles/jupyterhub/files/jupyterhub_config.py`. Change the `JupyterHub.uthenticator_class` from `firstuseauthenticator.FirstUseAuthenticator` to `LTI11Authenticator`. For example:
+Open the JupyterHub configuration file located in `ansible/roles/jupyterhub/files/jupyterhub_config.py`. Change the `JupyterHub.authenticator_class` from `firstuseauthenticator.FirstUseAuthenticator` to `LTI11Authenticator`. For example:
 
 Default authenticator setting:
 

ansible/hosts.example

@@ -1 +1,8 @@
-illumidesk ansible_ssh_host=<add_ip_address_here> ansible_ssh_port=22
+all:
+  hosts:
+    illumidesk:
+      ansible_host: 127.0.0.1
+      ansible_port: 22
+      ansible_user: root
+      ansible_ssh_private_key_file: /path/to/my/key/file
+      ansible_password:

ansible/roles/common/tasks/main.yml

@@ -13,7 +13,7 @@
   apt:
     upgrade: yes
     update_cache: yes
-    cache_valid_time: 3600
+    cache_valid_time: '3600'
 
 - name: install required system packages # noqa 403
   apt: