1.0 version of guide ToC

[yuvipanda]

@willingc, @minrk and @yuvipanda hashed out the contents of the ToC for a v1 of the guide (and the helm-chart). Raw Dump here. Let's split these into issues soon.

• Document the target Audience

  • Released version of helm chart

  • Command line, Docker, Kubernetes, GitHub familiarity

  • Test, Staging, Production workflow recommended

  • Default user database: sqlite (maybe have offline migrations - stop, dump, reload; destroying user servers and recreating db)

  • Expectation that someone familiar with or excited to learn Kubernetes administration and monitoring is needed at times (GUI or CLI)

  • Backups (default backup scheme - on for hub db - if using specific cloud providers - snapshot once a day of last 3 days, last week, last month)

  • Out of document scope

  • Using a developer preview version

  • Alternative databases PostgreSQL, mysql

• Add a Flowchart of process

• Prerequisites and Setting up a Deployment platform (suggestions on better wording - welcomed)

  • Creating a Kubernetes Cluster

  • Setting up Kubernetes on Google Cloud

  • Setting up Kubernetes on Microsoft Azure Container Service (ACS) (TODO: Add a note that Azure support is alpha)

  • OpenShift? (TODO)

  • Setting up Helm

  • Installation

  • Initialization

  • Next Step

***** From here down should be cloud provider agnostic (other than persistent and paid storage *****

• Hub - Getting started (Installation Guide for a test hub and/or a one-three day workshop)

  • Setting up JupyterHub

  • Prepare configuration file

  • Install JupyterHub

  • Setting up public access

  • Set up DNS (talk about A record, don't link to any particular registrar)

  • Setting up HTTPS

  • Automatic (with Let's encrypt + kube-lego)

  • Manual (specifying CA)

• Customizing your JupyterHub setup (Customization Guide)

  • User environment (and spawning done by admin)

  • Using an existing image -> dockerstacks right now data8 image

  • Extending your software stack with s2i -> jupyter-repo2docker

  • Pre-populating $HOME directory with notebooks when using Persistent Volumes

  • Persistent storage for each users (size, performance, turning it off) (TODO)

  • Authentication

    • Authenticating with OAuth2

    • Full Example of Google OAuth2

    • Example of using GitHub Auth (TODO)

    • Example of using Google Sheets auth ?! (TODO)

• Managing the Hub (Administrative Guide for Staging and Production)

  • Resource management (TODO)

  • Culler (timeout + every)

  • Setting memory and CPU guarantees / limits for your users (moved)

  • How to think about Costs (TODO)

  • Growing and shrinking capacity (TODO) - autoscaler

  • Backups

  • Upgrading helm chart (when new versions/configurations come out).

  • Upgrading JupyterHub and Helm Chart (Major releases)

  • Security considerations

  • Troubleshooting

  • Monitoring resource usage of users (TODO)

  • Looking at logs (kubectl logs and kubectl describe) (TODO)

  • GUI management of resources by student admins, TAs, or instructor (Kubernetes documentation reference)

  • looking at logs

  • a couple of common examples

  • Turning it all off -> save from being charged money when not in use

• Reference

  • Index

  • Glossary

    • JupyterHub
    • Kubernetes

  • References/Links

Out of Scope

Using PostgreSQL and mysql - Use your cloud provider's implementation

[willingc]

Next action: Review current documentation relative to this list. Open individual issues for uncompleted sections.

[consideRatio]

Next action:
Break this up into smaller pieces, this is to huge to consider!

[consideRatio]

Closing as outdated.