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**.