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.