Merge pull request #47 from willingc/playbooks

Improve comments and explanations in playbooks

ansible.cfg

@@ -1,3 +1,5 @@
+# Custom configuration settings for Ansible application
+
 [defaults]
 remote_user=root
 hostfile=./hosts

deploy.yml

@@ -1,4 +1,6 @@
 ---
+# The playbook deploys JupyterHub.
+# This file would be equivalent to a `sites.yml` file in Ansible terms.
 
 - hosts: jupyterhub_hosts
   tasks:

deploy_formgrade.yml

@@ -1,8 +1,8 @@
 ---
 
-# This is separate because it has to be run after the instructor's
-# user account is setup.
- 
+# This playbook is deployed separately and after `deploy.yml` since the
+# instructor's user account must be set up before deploying formgrader
+
 - hosts: jupyterhub_hosts
   roles:
     - formgrade

docs/source/index.rst

@@ -31,3 +31,4 @@ Contents
    use-nbgrader.rst
    teaching-checklist.md
    acknowledgment.rst
+   repo_contents.md

docs/source/repo_contents.md

@@ -0,0 +1,79 @@
+# Repository Contents
+
+## Ansible application
+
+### ansible.cfg
+
+Custom configuration settings for the Ansible application
+- We use to customize root access, root privileges, and ssh connection length.
+
+### ansible-conda
+
+Git submodule for `ansible-conda` application
+
+## Inventory (Ansible)
+
+### hosts.inventory
+
+Inventory file of servers (hosts) being managed by Ansible
+
+## Playbooks (Ansible)
+
+### deploy.yml (a.k.a. site.yml in Ansible jargon)
+
+### deploy_formgrade.yml
+
+### saveusers.yml
+
+## Variables (Ansible)
+
+### group_vars
+
+### host_vars
+
+## Roles (Ansible)
+
+### bash
+
+### common
+
+### cull_idle
+
+### formgrade
+
+### jupyterhub
+
+### nbgrader
+
+### newrelic
+
+### nginx
+
+### python
+
+### r
+
+### saveusers
+
+### supervisor
+
+
+## Development
+
+### .gitignore
+
+### .gitmodules
+
+### LICENSE
+
+### README.md
+
+## Documentation
+
+### readthedocs.yml
+
+Settings for readthedocs services
+
+### docs
+
+Directory containing sphinx documentation for the reference deployment.

group_vars/jupyterhub_hosts

@@ -1,33 +1,33 @@
 ---
 
 # These are global variables that are used across roles.
-# You shouldn't have to change these, to customize this deployment
-# for individual hosts, create and edit files in the host_vars folder.
+# NOTE: You shouldn't have to change these, to customize this deployment
+#       for individual hosts, create and edit files in the host_vars folder.
 
 # ---------------------------------------------------
-# JupyterHub config
+# JupyterHub config directories
 # ---------------------------------------------------
 
 jupyterhub_srv_dir: /srv/jupyterhub
 jupyterhub_config_dir: /etc/jupyterhub
 jupyterhub_log_dir: /var/log/jupyterhub
 
 # ---------------------------------------------------
-# Jupyter config
+# Jupyter config directories
 # ---------------------------------------------------
 
 jupyter_config_dir: /etc/jupyter
 jupyter_share_dir: /usr/local/share/jupyter
 jupyter_templates_dir: "{{jupyter_config_dir}}/templates"
 
 # ---------------------------------------------------
-# IPython config
+# IPython config directory
 # ---------------------------------------------------
 
 ipython_config_dir: /etc/ipython
 
 # ---------------------------------------------------
-# Nginx
+# Nginx configuration of SSL
 # ---------------------------------------------------
 
 # For externally provided SSL cert
@@ -40,7 +40,7 @@ letsencrypt_ssl_key_path: "/etc/letsencrypt/live/{{inventory_hostname}}/privkey.
 letsencrypt_ssl_cert_path: "/etc/letsencrypt/live/{{inventory_hostname}}/fullchain.pem"
 
 # ---------------------------------------------------
-# Nbgrader config
+# Nbgrader config directories
 # ---------------------------------------------------
 
 nbgrader_log_dir: /var/log/nbgrader

host_vars/hostname.example

@@ -1,60 +1,65 @@
 ---
 
-# Rename this files with the name of your host
-# and edit to customize its settings.
+# An example `hostname` file
+#
+# Edit this file to customize settings for a particular host.
+# Save as `hostname` without the `.example` suffix.
 
 # ---------------------------------------------------
-# Required
+# Required settings
 # ---------------------------------------------------
 
 # The base directory of user accounts
 home_dir: /home
 
-# The users that should be jupyterhub admins
+# Users with administrative privileges
 jupyterhub_admin_users:
   - instructor
 
-# The regular users able to use jupyterhub
+# Whitelist of jupyterhub users
 jupyterhub_users:
   - instructor
   - grader
   - student1
   - student2
 
-# Install r kernel
+# R kernel installation (default: false)
 install_r_kernel: false
 
-# Install bash kernel
+# bash kernel installation
 install_bash_kernel: true
 
-# The secret token to use for accessing the proxy
-# Create using something like `openssl rand -hex 32`
+# Secret token for proxy access
+# Create token using something like `openssl rand -hex 32` and
+# enter between quotation marks below
 proxy_auth_token: ''
 
-# nbgrader formgrade setup
+# nbgrader and formgrade settings (use_nbgrader default: false)
 use_nbgrader: false
 nbgrader_course_id: mycourse
 nbgrader_owner: instructor
 nbgrader_base_dir: "{{home_dir}}/{{nbgrader_owner}}/nbgrader/{{nbgrader_course_id}}"
-nbgrader_graders: 
+nbgrader_graders:
     - instructor
     - grader
 nbgrader_port: 5005
 
-# The API token formgrader will use to make requests of the Hub
-# Create using something like `openssl rand -hex 32`
+# The API token formgrader will use to make Hub requests
+# Create using something like `openssl rand -hex 32` and
+# enter between quotation marks below
 formgrader_hubapi_token: ''
 
 # Path of the Python 2.7 interpreter on the remote server
+# Note: Ansible requires Python 2.7 for provisioning so the path must be set
 ansible_python_interpreter: '/usr/bin/python2.7'
 
 # ---------------------------------------------------
-# Optional
+# Optional settings
 # ---------------------------------------------------
 
-# To mount local file systems populate this list.
-# This adds the entries to /etc/fstab, creates the mount point and mounts them.
-# Disks must be partitioned and formatted.
+# To mount local file systems populate this list. (Optional)
+# This adds the entries to /etc/fstab, creates the mount points,
+# and mounts them. Note: Disks must be partitioned and formatted.
 local_mounts: []
 #   - name: /mountpoint1
 #     src: /dev/sdb1
@@ -63,24 +68,34 @@ local_mounts: []
 #     src: /dev/sdc1
 #     fstype: ext3
 
-# If you want to use letsencrypt to generate SSL key/cert. Otherwise you MUST
-# put your key and cert into the security directory as security/ssl.crt and 
-# security/ssl.key
+# SSL using letsencrypt (optional - use letsencrypt default: false)
+# If using letsencrypt to generate SSL key/cert, set `use_letsencrypt` to `true`
+# Otherwise if not using letsencrypt for SSL, you MUST put your key and cert into the security directory as
+# `security/ssl.crt` and `security/ssl.key`
 use_letsencrypt: false
 letsencrypt_email: ''
 
-# If you want users to have /public_html/username directories set this to true
+# If users should have `/public_html/username` directories, set this to `true` (Optional)
 nginx_public_html: false
 
-# Optionally set this to a list of the GitHub usernames whose public
-# GitHub SSH keys will be installed to allow then to ssh to the server
-# as root.
+# List of the GitHub usernames who will receive root access via ssh
+# Public GitHub SSH keys will be installed to allow the user to ssh into the server as root.
 github_usernames: ['instructor', 'grader']
 
-# Optionally cull idle single user servers
+# Oauth (Optional - use oauth default: false)
+# Change `use_oauth` to `true` and set the other values appropriately
+# to enable GitHub OAuth.
+# If left as default `false`, PAM authentication will be used.
+use_oauth: false
+oauth_callback_url: https://mydomain.org/hub/oauth_callback
+oauth_client_id: ''
+oauth_client_secret: ''
+
+# Cull idle servers (Optional default: false)
+# Enable or disable cull idle single user servers
 use_cull_idle_servers: false
-# The username for culling idle servers. MUST be a user of JupyterHub,
-# so root won't work unless root can access JupyterHub
+# The username for culling idle servers. MUST be a user of JupyterHub.
+# For example, root won't work unless root can access JupyterHub.
 cull_idle_servers_owner: instructor
 # The API token for culling, create using something like `openssl rand -hex 32`
 cull_idle_servers_hubapi_token: ''
@@ -89,19 +104,12 @@ cull_every: 600
 # The idle timeout (in seconds)
 cull_timeout: 3600
 
-# Optionally set this as your Google Analytics Tracking ID
+# Set Google Analytics Tracking ID (Optional)
 ga_tracking_id: ''
 
-# Optionally set this as your NewRelic license key
+# Set NewRelic license key (Optional)
 newrelic_license_key: ''
 
-# Optionally change use_oauth to `true` and set the other values appropriately
-# to enable Github OAuth.
-use_oauth: false
-oauth_callback_url: https://mydomain.org/hub/oauth_callback
-oauth_client_id: ''
-oauth_client_secret: ''
-
-# Set this to the codename of your ubuntu version.
-# This is used to setup the R apt repositories which are based on this
+# Set user-friendly codename of installed ubuntu version. (Optional - Needed when using R)
+# This codename is used to setup the R apt repositories
 ubuntu_codename: wily

hosts.example

@@ -1,2 +1,15 @@
+# The `hosts` inventory file lists the JupyterHub servers managed by Ansible
+
+# This provides an inventory of host servers used for JupyterHub
+# Edit the fqdn (fully qualified domain name) for your hub server
+# For example:
+#
+# [jupyterhub_hosts]
+# www.example.com
+#
+# Save file as `hosts` (without the file type suffix) when done editing.
+# User tip: `hosts.example` is an example file where the contents are
+# ignored. Saving the file as `hosts` after editing is important.
+
 [jupyterhub_hosts]
 fqdn.goes.here

roles/bash/tasks/main.yml

@@ -1,11 +1,12 @@
 ---
+# This playbook installs a bash environment and kernel
 
 - name: pip install bash_kernel package
   pip: name={{item}} state=present editable=false
   become: true
   with_items:
       - bash_kernel
 
-- name: install bash_kernel
+- name: install bash_kernel for jupyter
   command: python3 -m bash_kernel.install
   become: true

roles/common/handlers/main.yml

@@ -1,9 +1,10 @@
 ---
+# This playbook restarts the network time protocol and ssh daemons
 
 - name: restart ntp
   service: name=ntp state=restarted
   become: true
-  
+
 - name: restart sshd
   service: name=ssh state=restarted
   become: true

roles/common/tasks/ntp.yml

@@ -1,7 +1,8 @@
 ---
+# This playbook installs the network time protocol daemon
 
 - name: install ntp
   apt: pkg=ntp state=present
   become: true
   notify:
-    - restart ntp
+    - restart ntp

roles/common/tasks/packages.yml

@@ -1,23 +1,26 @@
 ---
 
-- name: apt update
+# This playbook installs common packages used on a UNIX/Linux system
+
+- name: update apt
   apt: update_cache=yes cache_valid_time=3600
   become: yes
 
+# required to upgrade apt
 - name: install aptitude
   apt: pkg=aptitude
   become: yes
 
-# upgrade requires aptitude
-- name: apt upgrade
+# upgrade requires aptitude be installed
+- name: upgrade apt
   apt: upgrade=safe
   become: yes
 
-- name: build-essential
+- name: install build-essential tools
   apt: pkg=build-essential state=present
   become: true
 
-- name: other developer tools
+- name: install other developer tools
   apt: pkg={{item}} state=present
   become: true
   with_items: