From 87ffd179e0bacf9288a4be7e59d6935ce26f377d Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Wed, 8 Aug 2018 10:18:20 -0700 Subject: [PATCH 1/2] adding when to use tljh page --- docs/index.rst | 3 +- docs/topic/whentouse.rst | 82 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 docs/topic/whentouse.rst diff --git a/docs/index.rst b/docs/index.rst index eaf5931..a97a33c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,7 +3,8 @@ The Littlest JupyterHub ======================= A simple `JupyterHub `_ distribution for -a small (0-100) number of users on a single server. +a small (0-100) number of users on a single server. We recommend reading +:ref:`topic/whentouse` to determine if this is the right tool for you. Development Status ================== diff --git a/docs/topic/whentouse.rst b/docs/topic/whentouse.rst new file mode 100644 index 0000000..4a86c7a --- /dev/null +++ b/docs/topic/whentouse.rst @@ -0,0 +1,82 @@ +.. _topic/whentouse: + +=================================== +When to use The Littlest JupyterHub +=================================== + +The Littlest JupyterHub allows you to deploy a JupyterHub serving user sessions +on a single VM (or your own hardware). The Zero to JupyterHub guide allows you +to deploy JupyterHub on Kubernetes, making it much more scalable. +This page is a brief guide to determining which is best for your use-case. +Many of these ideas were first laid out in a +`blog post announcing TLJH `_. + +The Littlest JupyterHub +----------------------- + +The Littlest JupyterHub (TLJH) is an opinionated and pre-configured distribution +to deploy a JupyterHub on a single virtual machine (or your own hardware). +It is designed to be a more lightweight, flexible, and maintainable solution +for use-cases where scalability and cost-savings are not a huge concern. + +When to use TLJH +^^^^^^^^^^^^^^^^ + +* You want to provide easy access to a shared computational resource (CPU, RAM, data, etc) +* You only need to support up to ~100 people +* You aren't concerned about `over-provisioning your cluster `_. +* You don't need production-level security promises for your deployment + +TLJH main benefits +^^^^^^^^^^^^^^^^^^ + +* Simpler to deploy on many kinds of cloud services +* Faster to set up and tear down +* Allows administrators to quickly update user environments +* Is fairly simple in its technical makeup, reducing accidental complexity +* Supports any jupyter-based user workflows + +TLJH main drawbacks +^^^^^^^^^^^^^^^^^^^ + +The Littlest JupyterHub is more lightweight and easy to deploy, which makes it poorly suited for +large userbases or more fine-grained control over the computational resources +your deployment uses. It also doesn't use containers (both a good and a bad thing) +which means it does not support some security and networking features that some +may find useful. + + +Zero to JupyterHub for Kubernetes +--------------------------------- + +The other main distribution for deploying JupyterHub is the +`Zero to JupyterHub on Kubernetes `_ guide. +While Kubernetes is fantastic +for managing complex web infrastructure, sometimes it is a more complex +solution than needed. These points should help you decide if this is is the +tool for your use-case. + +When to use Z2JH +^^^^^^^^^^^^^^^^ + +* You may have more than ~100 users at a time +* You do want to avoid over-provisioning your cluster +* You want the security features of containers and Kubernetes +* You want a more "production-ready" JupyterHub deployment + +Z2JH main benefits +^^^^^^^^^^^^^^^^^^ + +* Runs on Kubernetes +* Scalable up to thousands of users +* More cost-effective at this scale (because you can automatically scale up/down the resources used) +* Uses container technology, and all the benefits that come with this +* Supports any user workflow that can run via a browser (Jupyter, RStudio, OpenRefine, etc) + +Z2JH main drawbacks +^^^^^^^^^^^^^^^^^^^ + +JupyterHub on Kubernetes is more complex to deploy because Kubernetes is more +complex. In addition, a more limited number of cloud providers offer +one-click solutions for running Kubernetes. This may provide more technical +overhead than you wish. From 54e9cfc93f19393397a458ac98111fe8f9693e39 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 10 Aug 2018 10:23:55 -0700 Subject: [PATCH 2/2] streamlining the whentouse page --- docs/index.rst | 1 + docs/topic/whentouse.rst | 86 +++++++++------------------------------- 2 files changed, 20 insertions(+), 67 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index a97a33c..085baaa 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -84,6 +84,7 @@ Topic guides provide in-depth explanations of specific topics. .. toctree:: :titlesonly: + topic/whentouse topic/requirements topic/security topic/customizing-installer diff --git a/docs/topic/whentouse.rst b/docs/topic/whentouse.rst index 4a86c7a..d2b77c8 100644 --- a/docs/topic/whentouse.rst +++ b/docs/topic/whentouse.rst @@ -4,79 +4,31 @@ When to use The Littlest JupyterHub =================================== -The Littlest JupyterHub allows you to deploy a JupyterHub serving user sessions -on a single VM (or your own hardware). The Zero to JupyterHub guide allows you -to deploy JupyterHub on Kubernetes, making it much more scalable. -This page is a brief guide to determining which is best for your use-case. +This page is a brief guide to determining whether to use The Littlest JupyterHub +(TLJH) or `Zero to JupyterHub for Kubernetes `_ (Z2JH). Many of these ideas were first laid out in a `blog post announcing TLJH `_. -The Littlest JupyterHub ------------------------ +**The Littlest JupyterHub (TLJH)** (`link `_) is an opinionated and pre-configured distribution +to deploy a JupyterHub on a **single machine** (in the cloud or on your own hardware). +It is designed to be a more lightweight and maintainable solution +for use-cases where size, scalability, and cost-savings are not a huge concern. -The Littlest JupyterHub (TLJH) is an opinionated and pre-configured distribution -to deploy a JupyterHub on a single virtual machine (or your own hardware). -It is designed to be a more lightweight, flexible, and maintainable solution -for use-cases where scalability and cost-savings are not a huge concern. +**Zero to JupyterHub on Kubernetes** (`link `_) allows you +to deploy JupyterHub on **Kubernetes**. This allows JupyterHub to scale to many thousands +of users, to flexibly grow/shrink the size of resources it needs, and to use +container technology in administering user sessions. -When to use TLJH -^^^^^^^^^^^^^^^^ +When to use TLJH vs. Z2JH +========================= -* You want to provide easy access to a shared computational resource (CPU, RAM, data, etc) -* You only need to support up to ~100 people -* You aren't concerned about `over-provisioning your cluster `_. -* You don't need production-level security promises for your deployment +The choice between TLJH and Z2JH ultimately comes down to only a few questoins: -TLJH main benefits -^^^^^^^^^^^^^^^^^^ +1. Do you want your hub and all users to live on a **single, larger machine** vs. spreading users on a **cluster of smaller machines** that are scaled up or down? -* Simpler to deploy on many kinds of cloud services -* Faster to set up and tear down -* Allows administrators to quickly update user environments -* Is fairly simple in its technical makeup, reducing accidental complexity -* Supports any jupyter-based user workflows + * If you can use a single machine, we recommend **The Littlest JupyterHub**. + * If you wish to use multiple machines, we recommend **Zero to JupyterHub for Kubernetes**. +2. Do you **need to use container technology**? -TLJH main drawbacks -^^^^^^^^^^^^^^^^^^^ - -The Littlest JupyterHub is more lightweight and easy to deploy, which makes it poorly suited for -large userbases or more fine-grained control over the computational resources -your deployment uses. It also doesn't use containers (both a good and a bad thing) -which means it does not support some security and networking features that some -may find useful. - - -Zero to JupyterHub for Kubernetes ---------------------------------- - -The other main distribution for deploying JupyterHub is the -`Zero to JupyterHub on Kubernetes `_ guide. -While Kubernetes is fantastic -for managing complex web infrastructure, sometimes it is a more complex -solution than needed. These points should help you decide if this is is the -tool for your use-case. - -When to use Z2JH -^^^^^^^^^^^^^^^^ - -* You may have more than ~100 users at a time -* You do want to avoid over-provisioning your cluster -* You want the security features of containers and Kubernetes -* You want a more "production-ready" JupyterHub deployment - -Z2JH main benefits -^^^^^^^^^^^^^^^^^^ - -* Runs on Kubernetes -* Scalable up to thousands of users -* More cost-effective at this scale (because you can automatically scale up/down the resources used) -* Uses container technology, and all the benefits that come with this -* Supports any user workflow that can run via a browser (Jupyter, RStudio, OpenRefine, etc) - -Z2JH main drawbacks -^^^^^^^^^^^^^^^^^^^ - -JupyterHub on Kubernetes is more complex to deploy because Kubernetes is more -complex. In addition, a more limited number of cloud providers offer -one-click solutions for running Kubernetes. This may provide more technical -overhead than you wish. + * If no, we recommend **The Littlest JupyterHub**. + * If yes, we recommend **Zero to JupyterHub for Kubernetes**.